Expressions
Every AST node in SQLGlot is represented by a subclass of Expression.
This module contains the implementation of all supported Expression types. Additionally,
it exposes a number of helper functions, which are mainly used to programmatically build
SQL expressions, such as sqlglot.expressions.select.
1""" 2## Expressions 3 4Every AST node in SQLGlot is represented by a subclass of `Expression`. 5 6This module contains the implementation of all supported `Expression` types. Additionally, 7it exposes a number of helper functions, which are mainly used to programmatically build 8SQL expressions, such as `sqlglot.expressions.select`. 9 10---- 11""" 12 13from __future__ import annotations 14 15import datetime 16import math 17import numbers 18import re 19import typing as t 20from collections import deque 21from copy import deepcopy 22from enum import auto 23 24from sqlglot.errors import ParseError 25from sqlglot.helper import ( 26 AutoName, 27 camel_to_snake_case, 28 ensure_collection, 29 seq_get, 30 split_num_words, 31 subclasses, 32) 33from sqlglot.tokens import Token 34 35if t.TYPE_CHECKING: 36 from sqlglot.dialects.dialect import DialectType 37 38 39class _Expression(type): 40 def __new__(cls, clsname, bases, attrs): 41 klass = super().__new__(cls, clsname, bases, attrs) 42 43 # When an Expression class is created, its key is automatically set to be 44 # the lowercase version of the class' name. 45 klass.key = clsname.lower() 46 47 # This is so that docstrings are not inherited in pdoc 48 klass.__doc__ = klass.__doc__ or "" 49 50 return klass 51 52 53class Expression(metaclass=_Expression): 54 """ 55 The base class for all expressions in a syntax tree. Each Expression encapsulates any necessary 56 context, such as its child expressions, their names (arg keys), and whether a given child expression 57 is optional or not. 58 59 Attributes: 60 key: a unique key for each class in the Expression hierarchy. This is useful for hashing 61 and representing expressions as strings. 62 arg_types: determines what arguments (child nodes) are supported by an expression. It 63 maps arg keys to booleans that indicate whether the corresponding args are optional. 64 65 Example: 66 >>> class Foo(Expression): 67 ... arg_types = {"this": True, "expression": False} 68 69 The above definition informs us that Foo is an Expression that requires an argument called 70 "this" and may also optionally receive an argument called "expression". 71 72 Args: 73 args: a mapping used for retrieving the arguments of an expression, given their arg keys. 74 parent: a reference to the parent expression (or None, in case of root expressions). 75 arg_key: the arg key an expression is associated with, i.e. the name its parent expression 76 uses to refer to it. 77 comments: a list of comments that are associated with a given expression. This is used in 78 order to preserve comments when transpiling SQL code. 79 _type: the `sqlglot.expressions.DataType` type of an expression. This is inferred by the 80 optimizer, in order to enable some transformations that require type information. 81 """ 82 83 key = "expression" 84 arg_types = {"this": True} 85 __slots__ = ("args", "parent", "arg_key", "comments", "_type", "_meta") 86 87 def __init__(self, **args: t.Any): 88 self.args: t.Dict[str, t.Any] = args 89 self.parent: t.Optional[Expression] = None 90 self.arg_key: t.Optional[str] = None 91 self.comments: t.Optional[t.List[str]] = None 92 self._type: t.Optional[DataType] = None 93 self._meta: t.Optional[t.Dict[str, t.Any]] = None 94 95 for arg_key, value in self.args.items(): 96 self._set_parent(arg_key, value) 97 98 def __eq__(self, other) -> bool: 99 return type(self) is type(other) and _norm_args(self) == _norm_args(other) 100 101 def __hash__(self) -> int: 102 return hash( 103 ( 104 self.key, 105 tuple( 106 (k, tuple(v) if isinstance(v, list) else v) for k, v in _norm_args(self).items() 107 ), 108 ) 109 ) 110 111 @property 112 def this(self): 113 """ 114 Retrieves the argument with key "this". 115 """ 116 return self.args.get("this") 117 118 @property 119 def expression(self): 120 """ 121 Retrieves the argument with key "expression". 122 """ 123 return self.args.get("expression") 124 125 @property 126 def expressions(self): 127 """ 128 Retrieves the argument with key "expressions". 129 """ 130 return self.args.get("expressions") or [] 131 132 def text(self, key) -> str: 133 """ 134 Returns a textual representation of the argument corresponding to "key". This can only be used 135 for args that are strings or leaf Expression instances, such as identifiers and literals. 136 """ 137 field = self.args.get(key) 138 if isinstance(field, str): 139 return field 140 if isinstance(field, (Identifier, Literal, Var)): 141 return field.this 142 if isinstance(field, (Star, Null)): 143 return field.name 144 return "" 145 146 @property 147 def is_string(self) -> bool: 148 """ 149 Checks whether a Literal expression is a string. 150 """ 151 return isinstance(self, Literal) and self.args["is_string"] 152 153 @property 154 def is_number(self) -> bool: 155 """ 156 Checks whether a Literal expression is a number. 157 """ 158 return isinstance(self, Literal) and not self.args["is_string"] 159 160 @property 161 def is_int(self) -> bool: 162 """ 163 Checks whether a Literal expression is an integer. 164 """ 165 if self.is_number: 166 try: 167 int(self.name) 168 return True 169 except ValueError: 170 pass 171 return False 172 173 @property 174 def is_star(self) -> bool: 175 """Checks whether an expression is a star.""" 176 return isinstance(self, Star) or (isinstance(self, Column) and isinstance(self.this, Star)) 177 178 @property 179 def alias(self) -> str: 180 """ 181 Returns the alias of the expression, or an empty string if it's not aliased. 182 """ 183 if isinstance(self.args.get("alias"), TableAlias): 184 return self.args["alias"].name 185 return self.text("alias") 186 187 @property 188 def name(self) -> str: 189 return self.text("this") 190 191 @property 192 def alias_or_name(self): 193 return self.alias or self.name 194 195 @property 196 def output_name(self): 197 """ 198 Name of the output column if this expression is a selection. 199 200 If the Expression has no output name, an empty string is returned. 201 202 Example: 203 >>> from sqlglot import parse_one 204 >>> parse_one("SELECT a").expressions[0].output_name 205 'a' 206 >>> parse_one("SELECT b AS c").expressions[0].output_name 207 'c' 208 >>> parse_one("SELECT 1 + 2").expressions[0].output_name 209 '' 210 """ 211 return "" 212 213 @property 214 def type(self) -> t.Optional[DataType]: 215 return self._type 216 217 @type.setter 218 def type(self, dtype: t.Optional[DataType | DataType.Type | str]) -> None: 219 if dtype and not isinstance(dtype, DataType): 220 dtype = DataType.build(dtype) 221 self._type = dtype # type: ignore 222 223 @property 224 def meta(self) -> t.Dict[str, t.Any]: 225 if self._meta is None: 226 self._meta = {} 227 return self._meta 228 229 def __deepcopy__(self, memo): 230 copy = self.__class__(**deepcopy(self.args)) 231 if self.comments is not None: 232 copy.comments = deepcopy(self.comments) 233 234 if self._type is not None: 235 copy._type = self._type.copy() 236 237 if self._meta is not None: 238 copy._meta = deepcopy(self._meta) 239 240 return copy 241 242 def copy(self): 243 """ 244 Returns a deep copy of the expression. 245 """ 246 new = deepcopy(self) 247 new.parent = self.parent 248 for item, parent, _ in new.bfs(): 249 if isinstance(item, Expression) and parent: 250 item.parent = parent 251 return new 252 253 def append(self, arg_key, value): 254 """ 255 Appends value to arg_key if it's a list or sets it as a new list. 256 257 Args: 258 arg_key (str): name of the list expression arg 259 value (Any): value to append to the list 260 """ 261 if not isinstance(self.args.get(arg_key), list): 262 self.args[arg_key] = [] 263 self.args[arg_key].append(value) 264 self._set_parent(arg_key, value) 265 266 def set(self, arg_key, value): 267 """ 268 Sets `arg_key` to `value`. 269 270 Args: 271 arg_key (str): name of the expression arg. 272 value: value to set the arg to. 273 """ 274 self.args[arg_key] = value 275 self._set_parent(arg_key, value) 276 277 def _set_parent(self, arg_key, value): 278 if isinstance(value, Expression): 279 value.parent = self 280 value.arg_key = arg_key 281 elif isinstance(value, list): 282 for v in value: 283 if isinstance(v, Expression): 284 v.parent = self 285 v.arg_key = arg_key 286 287 @property 288 def depth(self): 289 """ 290 Returns the depth of this tree. 291 """ 292 if self.parent: 293 return self.parent.depth + 1 294 return 0 295 296 def find(self, *expression_types, bfs=True): 297 """ 298 Returns the first node in this tree which matches at least one of 299 the specified types. 300 301 Args: 302 expression_types (type): the expression type(s) to match. 303 304 Returns: 305 The node which matches the criteria or None if no such node was found. 306 """ 307 return next(self.find_all(*expression_types, bfs=bfs), None) 308 309 def find_all(self, *expression_types, bfs=True): 310 """ 311 Returns a generator object which visits all nodes in this tree and only 312 yields those that match at least one of the specified expression types. 313 314 Args: 315 expression_types (type): the expression type(s) to match. 316 317 Returns: 318 The generator object. 319 """ 320 for expression, _, _ in self.walk(bfs=bfs): 321 if isinstance(expression, expression_types): 322 yield expression 323 324 def find_ancestor(self, *expression_types): 325 """ 326 Returns a nearest parent matching expression_types. 327 328 Args: 329 expression_types (type): the expression type(s) to match. 330 331 Returns: 332 The parent node. 333 """ 334 ancestor = self.parent 335 while ancestor and not isinstance(ancestor, expression_types): 336 ancestor = ancestor.parent 337 return ancestor 338 339 @property 340 def parent_select(self): 341 """ 342 Returns the parent select statement. 343 """ 344 return self.find_ancestor(Select) 345 346 def root(self) -> Expression: 347 """ 348 Returns the root expression of this tree. 349 """ 350 expression = self 351 while expression.parent: 352 expression = expression.parent 353 return expression 354 355 def walk(self, bfs=True, prune=None): 356 """ 357 Returns a generator object which visits all nodes in this tree. 358 359 Args: 360 bfs (bool): if set to True the BFS traversal order will be applied, 361 otherwise the DFS traversal will be used instead. 362 prune ((node, parent, arg_key) -> bool): callable that returns True if 363 the generator should stop traversing this branch of the tree. 364 365 Returns: 366 the generator object. 367 """ 368 if bfs: 369 yield from self.bfs(prune=prune) 370 else: 371 yield from self.dfs(prune=prune) 372 373 def dfs(self, parent=None, key=None, prune=None): 374 """ 375 Returns a generator object which visits all nodes in this tree in 376 the DFS (Depth-first) order. 377 378 Returns: 379 The generator object. 380 """ 381 parent = parent or self.parent 382 yield self, parent, key 383 if prune and prune(self, parent, key): 384 return 385 386 for k, v in self.args.items(): 387 for node in ensure_collection(v): 388 if isinstance(node, Expression): 389 yield from node.dfs(self, k, prune) 390 391 def bfs(self, prune=None): 392 """ 393 Returns a generator object which visits all nodes in this tree in 394 the BFS (Breadth-first) order. 395 396 Returns: 397 The generator object. 398 """ 399 queue = deque([(self, self.parent, None)]) 400 401 while queue: 402 item, parent, key = queue.popleft() 403 404 yield item, parent, key 405 if prune and prune(item, parent, key): 406 continue 407 408 if isinstance(item, Expression): 409 for k, v in item.args.items(): 410 for node in ensure_collection(v): 411 if isinstance(node, Expression): 412 queue.append((node, item, k)) 413 414 def unnest(self): 415 """ 416 Returns the first non parenthesis child or self. 417 """ 418 expression = self 419 while isinstance(expression, Paren): 420 expression = expression.this 421 return expression 422 423 def unalias(self): 424 """ 425 Returns the inner expression if this is an Alias. 426 """ 427 if isinstance(self, Alias): 428 return self.this 429 return self 430 431 def unnest_operands(self): 432 """ 433 Returns unnested operands as a tuple. 434 """ 435 return tuple(arg.unnest() for arg in self.args.values() if arg) 436 437 def flatten(self, unnest=True): 438 """ 439 Returns a generator which yields child nodes who's parents are the same class. 440 441 A AND B AND C -> [A, B, C] 442 """ 443 for node, _, _ in self.dfs(prune=lambda n, p, *_: p and not isinstance(n, self.__class__)): 444 if not isinstance(node, self.__class__): 445 yield node.unnest() if unnest else node 446 447 def __str__(self): 448 return self.sql() 449 450 def __repr__(self): 451 return self._to_s() 452 453 def sql(self, dialect: DialectType = None, **opts) -> str: 454 """ 455 Returns SQL string representation of this tree. 456 457 Args: 458 dialect: the dialect of the output SQL string (eg. "spark", "hive", "presto", "mysql"). 459 opts: other `sqlglot.generator.Generator` options. 460 461 Returns: 462 The SQL string. 463 """ 464 from sqlglot.dialects import Dialect 465 466 return Dialect.get_or_raise(dialect)().generate(self, **opts) 467 468 def _to_s(self, hide_missing: bool = True, level: int = 0) -> str: 469 indent = "" if not level else "\n" 470 indent += "".join([" "] * level) 471 left = f"({self.key.upper()} " 472 473 args: t.Dict[str, t.Any] = { 474 k: ", ".join( 475 v._to_s(hide_missing=hide_missing, level=level + 1) 476 if hasattr(v, "_to_s") 477 else str(v) 478 for v in ensure_collection(vs) 479 if v is not None 480 ) 481 for k, vs in self.args.items() 482 } 483 args["comments"] = self.comments 484 args["type"] = self.type 485 args = {k: v for k, v in args.items() if v or not hide_missing} 486 487 right = ", ".join(f"{k}: {v}" for k, v in args.items()) 488 right += ")" 489 490 return indent + left + right 491 492 def transform(self, fun, *args, copy=True, **kwargs): 493 """ 494 Recursively visits all tree nodes (excluding already transformed ones) 495 and applies the given transformation function to each node. 496 497 Args: 498 fun (function): a function which takes a node as an argument and returns a 499 new transformed node or the same node without modifications. If the function 500 returns None, then the corresponding node will be removed from the syntax tree. 501 copy (bool): if set to True a new tree instance is constructed, otherwise the tree is 502 modified in place. 503 504 Returns: 505 The transformed tree. 506 """ 507 node = self.copy() if copy else self 508 new_node = fun(node, *args, **kwargs) 509 510 if new_node is None or not isinstance(new_node, Expression): 511 return new_node 512 if new_node is not node: 513 new_node.parent = node.parent 514 return new_node 515 516 replace_children(new_node, lambda child: child.transform(fun, *args, copy=False, **kwargs)) 517 return new_node 518 519 def replace(self, expression): 520 """ 521 Swap out this expression with a new expression. 522 523 For example:: 524 525 >>> tree = Select().select("x").from_("tbl") 526 >>> tree.find(Column).replace(Column(this="y")) 527 (COLUMN this: y) 528 >>> tree.sql() 529 'SELECT y FROM tbl' 530 531 Args: 532 expression (Expression|None): new node 533 534 Returns: 535 The new expression or expressions. 536 """ 537 if not self.parent: 538 return expression 539 540 parent = self.parent 541 self.parent = None 542 543 replace_children(parent, lambda child: expression if child is self else child) 544 return expression 545 546 def pop(self): 547 """ 548 Remove this expression from its AST. 549 """ 550 self.replace(None) 551 552 def assert_is(self, type_): 553 """ 554 Assert that this `Expression` is an instance of `type_`. 555 556 If it is NOT an instance of `type_`, this raises an assertion error. 557 Otherwise, this returns this expression. 558 559 Examples: 560 This is useful for type security in chained expressions: 561 562 >>> import sqlglot 563 >>> sqlglot.parse_one("SELECT x from y").assert_is(Select).select("z").sql() 564 'SELECT x, z FROM y' 565 """ 566 assert isinstance(self, type_) 567 return self 568 569 def error_messages(self, args: t.Optional[t.Sequence] = None) -> t.List[str]: 570 """ 571 Checks if this expression is valid (e.g. all mandatory args are set). 572 573 Args: 574 args: a sequence of values that were used to instantiate a Func expression. This is used 575 to check that the provided arguments don't exceed the function argument limit. 576 577 Returns: 578 A list of error messages for all possible errors that were found. 579 """ 580 errors: t.List[str] = [] 581 582 for k in self.args: 583 if k not in self.arg_types: 584 errors.append(f"Unexpected keyword: '{k}' for {self.__class__}") 585 for k, mandatory in self.arg_types.items(): 586 v = self.args.get(k) 587 if mandatory and (v is None or (isinstance(v, list) and not v)): 588 errors.append(f"Required keyword: '{k}' missing for {self.__class__}") 589 590 if ( 591 args 592 and isinstance(self, Func) 593 and len(args) > len(self.arg_types) 594 and not self.is_var_len_args 595 ): 596 errors.append( 597 f"The number of provided arguments ({len(args)}) is greater than " 598 f"the maximum number of supported arguments ({len(self.arg_types)})" 599 ) 600 601 return errors 602 603 def dump(self): 604 """ 605 Dump this Expression to a JSON-serializable dict. 606 """ 607 from sqlglot.serde import dump 608 609 return dump(self) 610 611 @classmethod 612 def load(cls, obj): 613 """ 614 Load a dict (as returned by `Expression.dump`) into an Expression instance. 615 """ 616 from sqlglot.serde import load 617 618 return load(obj) 619 620 621IntoType = t.Union[ 622 str, 623 t.Type[Expression], 624 t.Collection[t.Union[str, t.Type[Expression]]], 625] 626 627 628class Condition(Expression): 629 def and_(self, *expressions, dialect=None, **opts): 630 """ 631 AND this condition with one or multiple expressions. 632 633 Example: 634 >>> condition("x=1").and_("y=1").sql() 635 'x = 1 AND y = 1' 636 637 Args: 638 *expressions (str | Expression): the SQL code strings to parse. 639 If an `Expression` instance is passed, it will be used as-is. 640 dialect (str): the dialect used to parse the input expression. 641 opts (kwargs): other options to use to parse the input expressions. 642 643 Returns: 644 And: the new condition. 645 """ 646 return and_(self, *expressions, dialect=dialect, **opts) 647 648 def or_(self, *expressions, dialect=None, **opts): 649 """ 650 OR this condition with one or multiple expressions. 651 652 Example: 653 >>> condition("x=1").or_("y=1").sql() 654 'x = 1 OR y = 1' 655 656 Args: 657 *expressions (str | Expression): the SQL code strings to parse. 658 If an `Expression` instance is passed, it will be used as-is. 659 dialect (str): the dialect used to parse the input expression. 660 opts (kwargs): other options to use to parse the input expressions. 661 662 Returns: 663 Or: the new condition. 664 """ 665 return or_(self, *expressions, dialect=dialect, **opts) 666 667 def not_(self): 668 """ 669 Wrap this condition with NOT. 670 671 Example: 672 >>> condition("x=1").not_().sql() 673 'NOT x = 1' 674 675 Returns: 676 Not: the new condition. 677 """ 678 return not_(self) 679 680 681class Predicate(Condition): 682 """Relationships like x = y, x > 1, x >= y.""" 683 684 685class DerivedTable(Expression): 686 @property 687 def alias_column_names(self): 688 table_alias = self.args.get("alias") 689 if not table_alias: 690 return [] 691 column_list = table_alias.assert_is(TableAlias).args.get("columns") or [] 692 return [c.name for c in column_list] 693 694 @property 695 def selects(self): 696 alias = self.args.get("alias") 697 698 if alias: 699 return alias.columns 700 return [] 701 702 @property 703 def named_selects(self): 704 return [select.output_name for select in self.selects] 705 706 707class Unionable(Expression): 708 def union(self, expression, distinct=True, dialect=None, **opts): 709 """ 710 Builds a UNION expression. 711 712 Example: 713 >>> import sqlglot 714 >>> sqlglot.parse_one("SELECT * FROM foo").union("SELECT * FROM bla").sql() 715 'SELECT * FROM foo UNION SELECT * FROM bla' 716 717 Args: 718 expression (str | Expression): the SQL code string. 719 If an `Expression` instance is passed, it will be used as-is. 720 distinct (bool): set the DISTINCT flag if and only if this is true. 721 dialect (str): the dialect used to parse the input expression. 722 opts (kwargs): other options to use to parse the input expressions. 723 Returns: 724 Union: the Union expression. 725 """ 726 return union(left=self, right=expression, distinct=distinct, dialect=dialect, **opts) 727 728 def intersect(self, expression, distinct=True, dialect=None, **opts): 729 """ 730 Builds an INTERSECT expression. 731 732 Example: 733 >>> import sqlglot 734 >>> sqlglot.parse_one("SELECT * FROM foo").intersect("SELECT * FROM bla").sql() 735 'SELECT * FROM foo INTERSECT SELECT * FROM bla' 736 737 Args: 738 expression (str | Expression): the SQL code string. 739 If an `Expression` instance is passed, it will be used as-is. 740 distinct (bool): set the DISTINCT flag if and only if this is true. 741 dialect (str): the dialect used to parse the input expression. 742 opts (kwargs): other options to use to parse the input expressions. 743 Returns: 744 Intersect: the Intersect expression 745 """ 746 return intersect(left=self, right=expression, distinct=distinct, dialect=dialect, **opts) 747 748 def except_(self, expression, distinct=True, dialect=None, **opts): 749 """ 750 Builds an EXCEPT expression. 751 752 Example: 753 >>> import sqlglot 754 >>> sqlglot.parse_one("SELECT * FROM foo").except_("SELECT * FROM bla").sql() 755 'SELECT * FROM foo EXCEPT SELECT * FROM bla' 756 757 Args: 758 expression (str | Expression): the SQL code string. 759 If an `Expression` instance is passed, it will be used as-is. 760 distinct (bool): set the DISTINCT flag if and only if this is true. 761 dialect (str): the dialect used to parse the input expression. 762 opts (kwargs): other options to use to parse the input expressions. 763 Returns: 764 Except: the Except expression 765 """ 766 return except_(left=self, right=expression, distinct=distinct, dialect=dialect, **opts) 767 768 769class UDTF(DerivedTable, Unionable): 770 pass 771 772 773class Cache(Expression): 774 arg_types = { 775 "with": False, 776 "this": True, 777 "lazy": False, 778 "options": False, 779 "expression": False, 780 } 781 782 783class Uncache(Expression): 784 arg_types = {"this": True, "exists": False} 785 786 787class Create(Expression): 788 arg_types = { 789 "with": False, 790 "this": True, 791 "kind": True, 792 "expression": False, 793 "exists": False, 794 "properties": False, 795 "replace": False, 796 "unique": False, 797 "indexes": False, 798 "no_schema_binding": False, 799 "begin": False, 800 } 801 802 803class Describe(Expression): 804 arg_types = {"this": True, "kind": False} 805 806 807class Set(Expression): 808 arg_types = {"expressions": True} 809 810 811class SetItem(Expression): 812 arg_types = { 813 "this": False, 814 "expressions": False, 815 "kind": False, 816 "collate": False, # MySQL SET NAMES statement 817 "global": False, 818 } 819 820 821class Show(Expression): 822 arg_types = { 823 "this": True, 824 "target": False, 825 "offset": False, 826 "limit": False, 827 "like": False, 828 "where": False, 829 "db": False, 830 "full": False, 831 "mutex": False, 832 "query": False, 833 "channel": False, 834 "global": False, 835 "log": False, 836 "position": False, 837 "types": False, 838 } 839 840 841class UserDefinedFunction(Expression): 842 arg_types = {"this": True, "expressions": False, "wrapped": False} 843 844 845class CharacterSet(Expression): 846 arg_types = {"this": True, "default": False} 847 848 849class With(Expression): 850 arg_types = {"expressions": True, "recursive": False} 851 852 @property 853 def recursive(self) -> bool: 854 return bool(self.args.get("recursive")) 855 856 857class WithinGroup(Expression): 858 arg_types = {"this": True, "expression": False} 859 860 861class CTE(DerivedTable): 862 arg_types = {"this": True, "alias": True} 863 864 865class TableAlias(Expression): 866 arg_types = {"this": False, "columns": False} 867 868 @property 869 def columns(self): 870 return self.args.get("columns") or [] 871 872 873class BitString(Condition): 874 pass 875 876 877class HexString(Condition): 878 pass 879 880 881class ByteString(Condition): 882 pass 883 884 885class Column(Condition): 886 arg_types = {"this": True, "table": False, "db": False, "catalog": False} 887 888 @property 889 def table(self) -> str: 890 return self.text("table") 891 892 @property 893 def db(self) -> str: 894 return self.text("db") 895 896 @property 897 def catalog(self) -> str: 898 return self.text("catalog") 899 900 @property 901 def output_name(self) -> str: 902 return self.name 903 904 905class ColumnDef(Expression): 906 arg_types = { 907 "this": True, 908 "kind": False, 909 "constraints": False, 910 "exists": False, 911 } 912 913 914class AlterColumn(Expression): 915 arg_types = { 916 "this": True, 917 "dtype": False, 918 "collate": False, 919 "using": False, 920 "default": False, 921 "drop": False, 922 } 923 924 925class RenameTable(Expression): 926 pass 927 928 929class ColumnConstraint(Expression): 930 arg_types = {"this": False, "kind": True} 931 932 933class ColumnConstraintKind(Expression): 934 pass 935 936 937class AutoIncrementColumnConstraint(ColumnConstraintKind): 938 pass 939 940 941class CaseSpecificColumnConstraint(ColumnConstraintKind): 942 arg_types = {"not_": True} 943 944 945class CharacterSetColumnConstraint(ColumnConstraintKind): 946 arg_types = {"this": True} 947 948 949class CheckColumnConstraint(ColumnConstraintKind): 950 pass 951 952 953class CollateColumnConstraint(ColumnConstraintKind): 954 pass 955 956 957class CommentColumnConstraint(ColumnConstraintKind): 958 pass 959 960 961class CompressColumnConstraint(ColumnConstraintKind): 962 pass 963 964 965class DateFormatColumnConstraint(ColumnConstraintKind): 966 arg_types = {"this": True} 967 968 969class DefaultColumnConstraint(ColumnConstraintKind): 970 pass 971 972 973class EncodeColumnConstraint(ColumnConstraintKind): 974 pass 975 976 977class GeneratedAsIdentityColumnConstraint(ColumnConstraintKind): 978 # this: True -> ALWAYS, this: False -> BY DEFAULT 979 arg_types = { 980 "this": False, 981 "start": False, 982 "increment": False, 983 "minvalue": False, 984 "maxvalue": False, 985 "cycle": False, 986 } 987 988 989class InlineLengthColumnConstraint(ColumnConstraintKind): 990 pass 991 992 993class NotNullColumnConstraint(ColumnConstraintKind): 994 arg_types = {"allow_null": False} 995 996 997class PrimaryKeyColumnConstraint(ColumnConstraintKind): 998 arg_types = {"desc": False} 999 1000 1001class TitleColumnConstraint(ColumnConstraintKind): 1002 pass 1003 1004 1005class UniqueColumnConstraint(ColumnConstraintKind): 1006 arg_types: t.Dict[str, t.Any] = {} 1007 1008 1009class UppercaseColumnConstraint(ColumnConstraintKind): 1010 arg_types: t.Dict[str, t.Any] = {} 1011 1012 1013class PathColumnConstraint(ColumnConstraintKind): 1014 pass 1015 1016 1017class Constraint(Expression): 1018 arg_types = {"this": True, "expressions": True} 1019 1020 1021class Delete(Expression): 1022 arg_types = {"with": False, "this": False, "using": False, "where": False} 1023 1024 1025class Drop(Expression): 1026 arg_types = { 1027 "this": False, 1028 "kind": False, 1029 "exists": False, 1030 "temporary": False, 1031 "materialized": False, 1032 "cascade": False, 1033 } 1034 1035 1036class Filter(Expression): 1037 arg_types = {"this": True, "expression": True} 1038 1039 1040class Check(Expression): 1041 pass 1042 1043 1044class Directory(Expression): 1045 # https://spark.apache.org/docs/3.0.0-preview/sql-ref-syntax-dml-insert-overwrite-directory-hive.html 1046 arg_types = {"this": True, "local": False, "row_format": False} 1047 1048 1049class ForeignKey(Expression): 1050 arg_types = { 1051 "expressions": True, 1052 "reference": False, 1053 "delete": False, 1054 "update": False, 1055 } 1056 1057 1058class PrimaryKey(Expression): 1059 arg_types = {"expressions": True, "options": False} 1060 1061 1062class Unique(Expression): 1063 arg_types = {"expressions": True} 1064 1065 1066# https://www.postgresql.org/docs/9.1/sql-selectinto.html 1067# https://docs.aws.amazon.com/redshift/latest/dg/r_SELECT_INTO.html#r_SELECT_INTO-examples 1068class Into(Expression): 1069 arg_types = {"this": True, "temporary": False, "unlogged": False} 1070 1071 1072class From(Expression): 1073 arg_types = {"expressions": True} 1074 1075 1076class Having(Expression): 1077 pass 1078 1079 1080class Hint(Expression): 1081 arg_types = {"expressions": True} 1082 1083 1084class JoinHint(Expression): 1085 arg_types = {"this": True, "expressions": True} 1086 1087 1088class Identifier(Expression): 1089 arg_types = {"this": True, "quoted": False} 1090 1091 @property 1092 def quoted(self): 1093 return bool(self.args.get("quoted")) 1094 1095 def __eq__(self, other): 1096 return isinstance(other, self.__class__) and _norm_arg(self.this) == _norm_arg(other.this) 1097 1098 def __hash__(self): 1099 return hash((self.key, self.this.lower())) 1100 1101 @property 1102 def output_name(self): 1103 return self.name 1104 1105 1106class Index(Expression): 1107 arg_types = { 1108 "this": False, 1109 "table": False, 1110 "where": False, 1111 "columns": False, 1112 "unique": False, 1113 "primary": False, 1114 "amp": False, # teradata 1115 } 1116 1117 1118class Insert(Expression): 1119 arg_types = { 1120 "with": False, 1121 "this": True, 1122 "expression": False, 1123 "overwrite": False, 1124 "exists": False, 1125 "partition": False, 1126 "alternative": False, 1127 } 1128 1129 1130# https://dev.mysql.com/doc/refman/8.0/en/charset-introducer.html 1131class Introducer(Expression): 1132 arg_types = {"this": True, "expression": True} 1133 1134 1135# national char, like n'utf8' 1136class National(Expression): 1137 pass 1138 1139 1140class LoadData(Expression): 1141 arg_types = { 1142 "this": True, 1143 "local": False, 1144 "overwrite": False, 1145 "inpath": True, 1146 "partition": False, 1147 "input_format": False, 1148 "serde": False, 1149 } 1150 1151 1152class Partition(Expression): 1153 arg_types = {"expressions": True} 1154 1155 1156class Fetch(Expression): 1157 arg_types = {"direction": False, "count": False} 1158 1159 1160class Group(Expression): 1161 arg_types = { 1162 "expressions": False, 1163 "grouping_sets": False, 1164 "cube": False, 1165 "rollup": False, 1166 } 1167 1168 1169class Lambda(Expression): 1170 arg_types = {"this": True, "expressions": True} 1171 1172 1173class Limit(Expression): 1174 arg_types = {"this": False, "expression": True} 1175 1176 1177class Literal(Condition): 1178 arg_types = {"this": True, "is_string": True} 1179 1180 def __eq__(self, other): 1181 return ( 1182 isinstance(other, Literal) 1183 and self.this == other.this 1184 and self.args["is_string"] == other.args["is_string"] 1185 ) 1186 1187 def __hash__(self): 1188 return hash((self.key, self.this, self.args["is_string"])) 1189 1190 @classmethod 1191 def number(cls, number) -> Literal: 1192 return cls(this=str(number), is_string=False) 1193 1194 @classmethod 1195 def string(cls, string) -> Literal: 1196 return cls(this=str(string), is_string=True) 1197 1198 @property 1199 def output_name(self): 1200 return self.name 1201 1202 1203class Join(Expression): 1204 arg_types = { 1205 "this": True, 1206 "on": False, 1207 "side": False, 1208 "kind": False, 1209 "using": False, 1210 "natural": False, 1211 } 1212 1213 @property 1214 def kind(self): 1215 return self.text("kind").upper() 1216 1217 @property 1218 def side(self): 1219 return self.text("side").upper() 1220 1221 @property 1222 def alias_or_name(self): 1223 return self.this.alias_or_name 1224 1225 def on(self, *expressions, append=True, dialect=None, copy=True, **opts): 1226 """ 1227 Append to or set the ON expressions. 1228 1229 Example: 1230 >>> import sqlglot 1231 >>> sqlglot.parse_one("JOIN x", into=Join).on("y = 1").sql() 1232 'JOIN x ON y = 1' 1233 1234 Args: 1235 *expressions (str | Expression): the SQL code strings to parse. 1236 If an `Expression` instance is passed, it will be used as-is. 1237 Multiple expressions are combined with an AND operator. 1238 append (bool): if `True`, AND the new expressions to any existing expression. 1239 Otherwise, this resets the expression. 1240 dialect (str): the dialect used to parse the input expressions. 1241 copy (bool): if `False`, modify this expression instance in-place. 1242 opts (kwargs): other options to use to parse the input expressions. 1243 1244 Returns: 1245 Join: the modified join expression. 1246 """ 1247 join = _apply_conjunction_builder( 1248 *expressions, 1249 instance=self, 1250 arg="on", 1251 append=append, 1252 dialect=dialect, 1253 copy=copy, 1254 **opts, 1255 ) 1256 1257 if join.kind == "CROSS": 1258 join.set("kind", None) 1259 1260 return join 1261 1262 def using(self, *expressions, append=True, dialect=None, copy=True, **opts): 1263 """ 1264 Append to or set the USING expressions. 1265 1266 Example: 1267 >>> import sqlglot 1268 >>> sqlglot.parse_one("JOIN x", into=Join).using("foo", "bla").sql() 1269 'JOIN x USING (foo, bla)' 1270 1271 Args: 1272 *expressions (str | Expression): the SQL code strings to parse. 1273 If an `Expression` instance is passed, it will be used as-is. 1274 append (bool): if `True`, concatenate the new expressions to the existing "using" list. 1275 Otherwise, this resets the expression. 1276 dialect (str): the dialect used to parse the input expressions. 1277 copy (bool): if `False`, modify this expression instance in-place. 1278 opts (kwargs): other options to use to parse the input expressions. 1279 1280 Returns: 1281 Join: the modified join expression. 1282 """ 1283 join = _apply_list_builder( 1284 *expressions, 1285 instance=self, 1286 arg="using", 1287 append=append, 1288 dialect=dialect, 1289 copy=copy, 1290 **opts, 1291 ) 1292 1293 if join.kind == "CROSS": 1294 join.set("kind", None) 1295 1296 return join 1297 1298 1299class Lateral(UDTF): 1300 arg_types = {"this": True, "view": False, "outer": False, "alias": False} 1301 1302 1303class MatchRecognize(Expression): 1304 arg_types = { 1305 "partition_by": False, 1306 "order": False, 1307 "measures": False, 1308 "rows": False, 1309 "after": False, 1310 "pattern": False, 1311 "define": False, 1312 } 1313 1314 1315# Clickhouse FROM FINAL modifier 1316# https://clickhouse.com/docs/en/sql-reference/statements/select/from/#final-modifier 1317class Final(Expression): 1318 pass 1319 1320 1321class Offset(Expression): 1322 arg_types = {"this": False, "expression": True} 1323 1324 1325class Order(Expression): 1326 arg_types = {"this": False, "expressions": True} 1327 1328 1329# hive specific sorts 1330# https://cwiki.apache.org/confluence/display/Hive/LanguageManual+SortBy 1331class Cluster(Order): 1332 pass 1333 1334 1335class Distribute(Order): 1336 pass 1337 1338 1339class Sort(Order): 1340 pass 1341 1342 1343class Ordered(Expression): 1344 arg_types = {"this": True, "desc": True, "nulls_first": True} 1345 1346 1347class Property(Expression): 1348 arg_types = {"this": True, "value": True} 1349 1350 1351class AfterJournalProperty(Property): 1352 arg_types = {"no": True, "dual": False, "local": False} 1353 1354 1355class AlgorithmProperty(Property): 1356 arg_types = {"this": True} 1357 1358 1359class AutoIncrementProperty(Property): 1360 arg_types = {"this": True} 1361 1362 1363class BlockCompressionProperty(Property): 1364 arg_types = {"autotemp": False, "always": False, "default": True, "manual": True, "never": True} 1365 1366 1367class CharacterSetProperty(Property): 1368 arg_types = {"this": True, "default": True} 1369 1370 1371class ChecksumProperty(Property): 1372 arg_types = {"on": False, "default": False} 1373 1374 1375class CollateProperty(Property): 1376 arg_types = {"this": True} 1377 1378 1379class DataBlocksizeProperty(Property): 1380 arg_types = {"size": False, "units": False, "min": False, "default": False} 1381 1382 1383class DefinerProperty(Property): 1384 arg_types = {"this": True} 1385 1386 1387class DistKeyProperty(Property): 1388 arg_types = {"this": True} 1389 1390 1391class DistStyleProperty(Property): 1392 arg_types = {"this": True} 1393 1394 1395class EngineProperty(Property): 1396 arg_types = {"this": True} 1397 1398 1399class ExecuteAsProperty(Property): 1400 arg_types = {"this": True} 1401 1402 1403class ExternalProperty(Property): 1404 arg_types = {"this": False} 1405 1406 1407class FallbackProperty(Property): 1408 arg_types = {"no": True, "protection": False} 1409 1410 1411class FileFormatProperty(Property): 1412 arg_types = {"this": True} 1413 1414 1415class FreespaceProperty(Property): 1416 arg_types = {"this": True, "percent": False} 1417 1418 1419class IsolatedLoadingProperty(Property): 1420 arg_types = { 1421 "no": True, 1422 "concurrent": True, 1423 "for_all": True, 1424 "for_insert": True, 1425 "for_none": True, 1426 } 1427 1428 1429class JournalProperty(Property): 1430 arg_types = {"no": True, "dual": False, "before": False} 1431 1432 1433class LanguageProperty(Property): 1434 arg_types = {"this": True} 1435 1436 1437class LikeProperty(Property): 1438 arg_types = {"this": True, "expressions": False} 1439 1440 1441class LocationProperty(Property): 1442 arg_types = {"this": True} 1443 1444 1445class LockingProperty(Property): 1446 arg_types = { 1447 "this": False, 1448 "kind": True, 1449 "for_or_in": True, 1450 "lock_type": True, 1451 "override": False, 1452 } 1453 1454 1455class LogProperty(Property): 1456 arg_types = {"no": True} 1457 1458 1459class MaterializedProperty(Property): 1460 arg_types = {"this": False} 1461 1462 1463class MergeBlockRatioProperty(Property): 1464 arg_types = {"this": False, "no": False, "default": False, "percent": False} 1465 1466 1467class NoPrimaryIndexProperty(Property): 1468 arg_types = {"this": False} 1469 1470 1471class OnCommitProperty(Property): 1472 arg_type = {"this": False} 1473 1474 1475class PartitionedByProperty(Property): 1476 arg_types = {"this": True} 1477 1478 1479class ReturnsProperty(Property): 1480 arg_types = {"this": True, "is_table": False, "table": False} 1481 1482 1483class RowFormatDelimitedProperty(Property): 1484 # https://cwiki.apache.org/confluence/display/hive/languagemanual+dml 1485 arg_types = { 1486 "fields": False, 1487 "escaped": False, 1488 "collection_items": False, 1489 "map_keys": False, 1490 "lines": False, 1491 "null": False, 1492 "serde": False, 1493 } 1494 1495 1496class RowFormatSerdeProperty(Property): 1497 arg_types = {"this": True} 1498 1499 1500class SchemaCommentProperty(Property): 1501 arg_types = {"this": True} 1502 1503 1504class SerdeProperties(Property): 1505 arg_types = {"expressions": True} 1506 1507 1508class SetProperty(Property): 1509 arg_types = {"multi": True} 1510 1511 1512class SortKeyProperty(Property): 1513 arg_types = {"this": True, "compound": False} 1514 1515 1516class SqlSecurityProperty(Property): 1517 arg_types = {"definer": True} 1518 1519 1520class TableFormatProperty(Property): 1521 arg_types = {"this": True} 1522 1523 1524class TemporaryProperty(Property): 1525 arg_types = {"global_": True} 1526 1527 1528class TransientProperty(Property): 1529 arg_types = {"this": False} 1530 1531 1532class VolatilityProperty(Property): 1533 arg_types = {"this": True} 1534 1535 1536class WithDataProperty(Property): 1537 arg_types = {"no": True, "statistics": False} 1538 1539 1540class WithJournalTableProperty(Property): 1541 arg_types = {"this": True} 1542 1543 1544class Properties(Expression): 1545 arg_types = {"expressions": True} 1546 1547 NAME_TO_PROPERTY = { 1548 "ALGORITHM": AlgorithmProperty, 1549 "AUTO_INCREMENT": AutoIncrementProperty, 1550 "CHARACTER SET": CharacterSetProperty, 1551 "COLLATE": CollateProperty, 1552 "COMMENT": SchemaCommentProperty, 1553 "DEFINER": DefinerProperty, 1554 "DISTKEY": DistKeyProperty, 1555 "DISTSTYLE": DistStyleProperty, 1556 "ENGINE": EngineProperty, 1557 "EXECUTE AS": ExecuteAsProperty, 1558 "FORMAT": FileFormatProperty, 1559 "LANGUAGE": LanguageProperty, 1560 "LOCATION": LocationProperty, 1561 "PARTITIONED_BY": PartitionedByProperty, 1562 "RETURNS": ReturnsProperty, 1563 "SORTKEY": SortKeyProperty, 1564 "TABLE_FORMAT": TableFormatProperty, 1565 } 1566 1567 PROPERTY_TO_NAME = {v: k for k, v in NAME_TO_PROPERTY.items()} 1568 1569 # CREATE property locations 1570 # Form: schema specified 1571 # create [POST_CREATE] 1572 # table a [POST_NAME] 1573 # (b int) [POST_SCHEMA] 1574 # with ([POST_WITH]) 1575 # index (b) [POST_INDEX] 1576 # 1577 # Form: alias selection 1578 # create [POST_CREATE] 1579 # table a [POST_NAME] 1580 # as [POST_ALIAS] (select * from b) [POST_EXPRESSION] 1581 # index (c) [POST_INDEX] 1582 class Location(AutoName): 1583 POST_CREATE = auto() 1584 POST_NAME = auto() 1585 POST_SCHEMA = auto() 1586 POST_WITH = auto() 1587 POST_ALIAS = auto() 1588 POST_EXPRESSION = auto() 1589 POST_INDEX = auto() 1590 UNSUPPORTED = auto() 1591 1592 @classmethod 1593 def from_dict(cls, properties_dict) -> Properties: 1594 expressions = [] 1595 for key, value in properties_dict.items(): 1596 property_cls = cls.NAME_TO_PROPERTY.get(key.upper()) 1597 if property_cls: 1598 expressions.append(property_cls(this=convert(value))) 1599 else: 1600 expressions.append(Property(this=Literal.string(key), value=convert(value))) 1601 1602 return cls(expressions=expressions) 1603 1604 1605class Qualify(Expression): 1606 pass 1607 1608 1609# https://www.ibm.com/docs/en/ias?topic=procedures-return-statement-in-sql 1610class Return(Expression): 1611 pass 1612 1613 1614class Reference(Expression): 1615 arg_types = {"this": True, "expressions": False, "options": False} 1616 1617 1618class Tuple(Expression): 1619 arg_types = {"expressions": False} 1620 1621 1622class Subqueryable(Unionable): 1623 def subquery(self, alias=None, copy=True) -> Subquery: 1624 """ 1625 Convert this expression to an aliased expression that can be used as a Subquery. 1626 1627 Example: 1628 >>> subquery = Select().select("x").from_("tbl").subquery() 1629 >>> Select().select("x").from_(subquery).sql() 1630 'SELECT x FROM (SELECT x FROM tbl)' 1631 1632 Args: 1633 alias (str | Identifier): an optional alias for the subquery 1634 copy (bool): if `False`, modify this expression instance in-place. 1635 1636 Returns: 1637 Alias: the subquery 1638 """ 1639 instance = _maybe_copy(self, copy) 1640 return Subquery( 1641 this=instance, 1642 alias=TableAlias(this=to_identifier(alias)), 1643 ) 1644 1645 def limit(self, expression, dialect=None, copy=True, **opts) -> Select: 1646 raise NotImplementedError 1647 1648 @property 1649 def ctes(self): 1650 with_ = self.args.get("with") 1651 if not with_: 1652 return [] 1653 return with_.expressions 1654 1655 @property 1656 def selects(self): 1657 raise NotImplementedError("Subqueryable objects must implement `selects`") 1658 1659 @property 1660 def named_selects(self): 1661 raise NotImplementedError("Subqueryable objects must implement `named_selects`") 1662 1663 def with_( 1664 self, 1665 alias, 1666 as_, 1667 recursive=None, 1668 append=True, 1669 dialect=None, 1670 copy=True, 1671 **opts, 1672 ): 1673 """ 1674 Append to or set the common table expressions. 1675 1676 Example: 1677 >>> Select().with_("tbl2", as_="SELECT * FROM tbl").select("x").from_("tbl2").sql() 1678 'WITH tbl2 AS (SELECT * FROM tbl) SELECT x FROM tbl2' 1679 1680 Args: 1681 alias (str | Expression): the SQL code string to parse as the table name. 1682 If an `Expression` instance is passed, this is used as-is. 1683 as_ (str | Expression): the SQL code string to parse as the table expression. 1684 If an `Expression` instance is passed, it will be used as-is. 1685 recursive (bool): set the RECURSIVE part of the expression. Defaults to `False`. 1686 append (bool): if `True`, add to any existing expressions. 1687 Otherwise, this resets the expressions. 1688 dialect (str): the dialect used to parse the input expression. 1689 copy (bool): if `False`, modify this expression instance in-place. 1690 opts (kwargs): other options to use to parse the input expressions. 1691 1692 Returns: 1693 Select: the modified expression. 1694 """ 1695 alias_expression = maybe_parse( 1696 alias, 1697 dialect=dialect, 1698 into=TableAlias, 1699 **opts, 1700 ) 1701 as_expression = maybe_parse( 1702 as_, 1703 dialect=dialect, 1704 **opts, 1705 ) 1706 cte = CTE( 1707 this=as_expression, 1708 alias=alias_expression, 1709 ) 1710 return _apply_child_list_builder( 1711 cte, 1712 instance=self, 1713 arg="with", 1714 append=append, 1715 copy=copy, 1716 into=With, 1717 properties={"recursive": recursive or False}, 1718 ) 1719 1720 1721QUERY_MODIFIERS = { 1722 "match": False, 1723 "laterals": False, 1724 "joins": False, 1725 "pivots": False, 1726 "where": False, 1727 "group": False, 1728 "having": False, 1729 "qualify": False, 1730 "windows": False, 1731 "distribute": False, 1732 "sort": False, 1733 "cluster": False, 1734 "order": False, 1735 "limit": False, 1736 "offset": False, 1737 "lock": False, 1738} 1739 1740 1741class Table(Expression): 1742 arg_types = { 1743 "this": True, 1744 "alias": False, 1745 "db": False, 1746 "catalog": False, 1747 "laterals": False, 1748 "joins": False, 1749 "pivots": False, 1750 "hints": False, 1751 "system_time": False, 1752 } 1753 1754 @property 1755 def db(self) -> str: 1756 return self.text("db") 1757 1758 @property 1759 def catalog(self) -> str: 1760 return self.text("catalog") 1761 1762 1763# See the TSQL "Querying data in a system-versioned temporal table" page 1764class SystemTime(Expression): 1765 arg_types = { 1766 "this": False, 1767 "expression": False, 1768 "kind": True, 1769 } 1770 1771 1772class Union(Subqueryable): 1773 arg_types = { 1774 "with": False, 1775 "this": True, 1776 "expression": True, 1777 "distinct": False, 1778 **QUERY_MODIFIERS, 1779 } 1780 1781 def limit(self, expression, dialect=None, copy=True, **opts) -> Select: 1782 """ 1783 Set the LIMIT expression. 1784 1785 Example: 1786 >>> select("1").union(select("1")).limit(1).sql() 1787 'SELECT * FROM (SELECT 1 UNION SELECT 1) AS _l_0 LIMIT 1' 1788 1789 Args: 1790 expression (str | int | Expression): the SQL code string to parse. 1791 This can also be an integer. 1792 If a `Limit` instance is passed, this is used as-is. 1793 If another `Expression` instance is passed, it will be wrapped in a `Limit`. 1794 dialect (str): the dialect used to parse the input expression. 1795 copy (bool): if `False`, modify this expression instance in-place. 1796 opts (kwargs): other options to use to parse the input expressions. 1797 1798 Returns: 1799 Select: The limited subqueryable. 1800 """ 1801 return ( 1802 select("*") 1803 .from_(self.subquery(alias="_l_0", copy=copy)) 1804 .limit(expression, dialect=dialect, copy=False, **opts) 1805 ) 1806 1807 def select( 1808 self, 1809 *expressions: str | Expression, 1810 append: bool = True, 1811 dialect: DialectType = None, 1812 copy: bool = True, 1813 **opts, 1814 ) -> Union: 1815 """Append to or set the SELECT of the union recursively. 1816 1817 Example: 1818 >>> from sqlglot import parse_one 1819 >>> parse_one("select a from x union select a from y union select a from z").select("b").sql() 1820 'SELECT a, b FROM x UNION SELECT a, b FROM y UNION SELECT a, b FROM z' 1821 1822 Args: 1823 *expressions: the SQL code strings to parse. 1824 If an `Expression` instance is passed, it will be used as-is. 1825 append: if `True`, add to any existing expressions. 1826 Otherwise, this resets the expressions. 1827 dialect: the dialect used to parse the input expressions. 1828 copy: if `False`, modify this expression instance in-place. 1829 opts: other options to use to parse the input expressions. 1830 1831 Returns: 1832 Union: the modified expression. 1833 """ 1834 this = self.copy() if copy else self 1835 this.this.unnest().select(*expressions, append=append, dialect=dialect, copy=False, **opts) 1836 this.expression.unnest().select( 1837 *expressions, append=append, dialect=dialect, copy=False, **opts 1838 ) 1839 return this 1840 1841 @property 1842 def named_selects(self): 1843 return self.this.unnest().named_selects 1844 1845 @property 1846 def is_star(self) -> bool: 1847 return self.this.is_star or self.expression.is_star 1848 1849 @property 1850 def selects(self): 1851 return self.this.unnest().selects 1852 1853 @property 1854 def left(self): 1855 return self.this 1856 1857 @property 1858 def right(self): 1859 return self.expression 1860 1861 1862class Except(Union): 1863 pass 1864 1865 1866class Intersect(Union): 1867 pass 1868 1869 1870class Unnest(UDTF): 1871 arg_types = { 1872 "expressions": True, 1873 "ordinality": False, 1874 "alias": False, 1875 "offset": False, 1876 } 1877 1878 1879class Update(Expression): 1880 arg_types = { 1881 "with": False, 1882 "this": False, 1883 "expressions": True, 1884 "from": False, 1885 "where": False, 1886 } 1887 1888 1889class Values(UDTF): 1890 arg_types = { 1891 "expressions": True, 1892 "ordinality": False, 1893 "alias": False, 1894 } 1895 1896 1897class Var(Expression): 1898 pass 1899 1900 1901class Schema(Expression): 1902 arg_types = {"this": False, "expressions": False} 1903 1904 1905# Used to represent the FOR UPDATE and FOR SHARE locking read types. 1906# https://dev.mysql.com/doc/refman/8.0/en/innodb-locking-reads.html 1907class Lock(Expression): 1908 arg_types = {"update": True} 1909 1910 1911class Select(Subqueryable): 1912 arg_types = { 1913 "with": False, 1914 "expressions": False, 1915 "hint": False, 1916 "distinct": False, 1917 "into": False, 1918 "from": False, 1919 **QUERY_MODIFIERS, 1920 } 1921 1922 def from_(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 1923 """ 1924 Set the FROM expression. 1925 1926 Example: 1927 >>> Select().from_("tbl").select("x").sql() 1928 'SELECT x FROM tbl' 1929 1930 Args: 1931 *expressions (str | Expression): the SQL code strings to parse. 1932 If a `From` instance is passed, this is used as-is. 1933 If another `Expression` instance is passed, it will be wrapped in a `From`. 1934 append (bool): if `True`, add to any existing expressions. 1935 Otherwise, this flattens all the `From` expression into a single expression. 1936 dialect (str): the dialect used to parse the input expression. 1937 copy (bool): if `False`, modify this expression instance in-place. 1938 opts (kwargs): other options to use to parse the input expressions. 1939 1940 Returns: 1941 Select: the modified expression. 1942 """ 1943 return _apply_child_list_builder( 1944 *expressions, 1945 instance=self, 1946 arg="from", 1947 append=append, 1948 copy=copy, 1949 prefix="FROM", 1950 into=From, 1951 dialect=dialect, 1952 **opts, 1953 ) 1954 1955 def group_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 1956 """ 1957 Set the GROUP BY expression. 1958 1959 Example: 1960 >>> Select().from_("tbl").select("x", "COUNT(1)").group_by("x").sql() 1961 'SELECT x, COUNT(1) FROM tbl GROUP BY x' 1962 1963 Args: 1964 *expressions (str | Expression): the SQL code strings to parse. 1965 If a `Group` instance is passed, this is used as-is. 1966 If another `Expression` instance is passed, it will be wrapped in a `Group`. 1967 If nothing is passed in then a group by is not applied to the expression 1968 append (bool): if `True`, add to any existing expressions. 1969 Otherwise, this flattens all the `Group` expression into a single expression. 1970 dialect (str): the dialect used to parse the input expression. 1971 copy (bool): if `False`, modify this expression instance in-place. 1972 opts (kwargs): other options to use to parse the input expressions. 1973 1974 Returns: 1975 Select: the modified expression. 1976 """ 1977 if not expressions: 1978 return self if not copy else self.copy() 1979 return _apply_child_list_builder( 1980 *expressions, 1981 instance=self, 1982 arg="group", 1983 append=append, 1984 copy=copy, 1985 prefix="GROUP BY", 1986 into=Group, 1987 dialect=dialect, 1988 **opts, 1989 ) 1990 1991 def order_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 1992 """ 1993 Set the ORDER BY expression. 1994 1995 Example: 1996 >>> Select().from_("tbl").select("x").order_by("x DESC").sql() 1997 'SELECT x FROM tbl ORDER BY x DESC' 1998 1999 Args: 2000 *expressions (str | Expression): the SQL code strings to parse. 2001 If a `Group` instance is passed, this is used as-is. 2002 If another `Expression` instance is passed, it will be wrapped in a `Order`. 2003 append (bool): if `True`, add to any existing expressions. 2004 Otherwise, this flattens all the `Order` expression into a single expression. 2005 dialect (str): the dialect used to parse the input expression. 2006 copy (bool): if `False`, modify this expression instance in-place. 2007 opts (kwargs): other options to use to parse the input expressions. 2008 2009 Returns: 2010 Select: the modified expression. 2011 """ 2012 return _apply_child_list_builder( 2013 *expressions, 2014 instance=self, 2015 arg="order", 2016 append=append, 2017 copy=copy, 2018 prefix="ORDER BY", 2019 into=Order, 2020 dialect=dialect, 2021 **opts, 2022 ) 2023 2024 def sort_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 2025 """ 2026 Set the SORT BY expression. 2027 2028 Example: 2029 >>> Select().from_("tbl").select("x").sort_by("x DESC").sql() 2030 'SELECT x FROM tbl SORT BY x DESC' 2031 2032 Args: 2033 *expressions (str | Expression): the SQL code strings to parse. 2034 If a `Group` instance is passed, this is used as-is. 2035 If another `Expression` instance is passed, it will be wrapped in a `SORT`. 2036 append (bool): if `True`, add to any existing expressions. 2037 Otherwise, this flattens all the `Order` expression into a single expression. 2038 dialect (str): the dialect used to parse the input expression. 2039 copy (bool): if `False`, modify this expression instance in-place. 2040 opts (kwargs): other options to use to parse the input expressions. 2041 2042 Returns: 2043 Select: the modified expression. 2044 """ 2045 return _apply_child_list_builder( 2046 *expressions, 2047 instance=self, 2048 arg="sort", 2049 append=append, 2050 copy=copy, 2051 prefix="SORT BY", 2052 into=Sort, 2053 dialect=dialect, 2054 **opts, 2055 ) 2056 2057 def cluster_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 2058 """ 2059 Set the CLUSTER BY expression. 2060 2061 Example: 2062 >>> Select().from_("tbl").select("x").cluster_by("x DESC").sql() 2063 'SELECT x FROM tbl CLUSTER BY x DESC' 2064 2065 Args: 2066 *expressions (str | Expression): the SQL code strings to parse. 2067 If a `Group` instance is passed, this is used as-is. 2068 If another `Expression` instance is passed, it will be wrapped in a `Cluster`. 2069 append (bool): if `True`, add to any existing expressions. 2070 Otherwise, this flattens all the `Order` expression into a single expression. 2071 dialect (str): the dialect used to parse the input expression. 2072 copy (bool): if `False`, modify this expression instance in-place. 2073 opts (kwargs): other options to use to parse the input expressions. 2074 2075 Returns: 2076 Select: the modified expression. 2077 """ 2078 return _apply_child_list_builder( 2079 *expressions, 2080 instance=self, 2081 arg="cluster", 2082 append=append, 2083 copy=copy, 2084 prefix="CLUSTER BY", 2085 into=Cluster, 2086 dialect=dialect, 2087 **opts, 2088 ) 2089 2090 def limit(self, expression, dialect=None, copy=True, **opts) -> Select: 2091 """ 2092 Set the LIMIT expression. 2093 2094 Example: 2095 >>> Select().from_("tbl").select("x").limit(10).sql() 2096 'SELECT x FROM tbl LIMIT 10' 2097 2098 Args: 2099 expression (str | int | Expression): the SQL code string to parse. 2100 This can also be an integer. 2101 If a `Limit` instance is passed, this is used as-is. 2102 If another `Expression` instance is passed, it will be wrapped in a `Limit`. 2103 dialect (str): the dialect used to parse the input expression. 2104 copy (bool): if `False`, modify this expression instance in-place. 2105 opts (kwargs): other options to use to parse the input expressions. 2106 2107 Returns: 2108 Select: the modified expression. 2109 """ 2110 return _apply_builder( 2111 expression=expression, 2112 instance=self, 2113 arg="limit", 2114 into=Limit, 2115 prefix="LIMIT", 2116 dialect=dialect, 2117 copy=copy, 2118 **opts, 2119 ) 2120 2121 def offset(self, expression, dialect=None, copy=True, **opts) -> Select: 2122 """ 2123 Set the OFFSET expression. 2124 2125 Example: 2126 >>> Select().from_("tbl").select("x").offset(10).sql() 2127 'SELECT x FROM tbl OFFSET 10' 2128 2129 Args: 2130 expression (str | int | Expression): the SQL code string to parse. 2131 This can also be an integer. 2132 If a `Offset` instance is passed, this is used as-is. 2133 If another `Expression` instance is passed, it will be wrapped in a `Offset`. 2134 dialect (str): the dialect used to parse the input expression. 2135 copy (bool): if `False`, modify this expression instance in-place. 2136 opts (kwargs): other options to use to parse the input expressions. 2137 2138 Returns: 2139 Select: the modified expression. 2140 """ 2141 return _apply_builder( 2142 expression=expression, 2143 instance=self, 2144 arg="offset", 2145 into=Offset, 2146 prefix="OFFSET", 2147 dialect=dialect, 2148 copy=copy, 2149 **opts, 2150 ) 2151 2152 def select( 2153 self, 2154 *expressions: str | Expression, 2155 append: bool = True, 2156 dialect: DialectType = None, 2157 copy: bool = True, 2158 **opts, 2159 ) -> Select: 2160 """ 2161 Append to or set the SELECT expressions. 2162 2163 Example: 2164 >>> Select().select("x", "y").sql() 2165 'SELECT x, y' 2166 2167 Args: 2168 *expressions: the SQL code strings to parse. 2169 If an `Expression` instance is passed, it will be used as-is. 2170 append: if `True`, add to any existing expressions. 2171 Otherwise, this resets the expressions. 2172 dialect: the dialect used to parse the input expressions. 2173 copy: if `False`, modify this expression instance in-place. 2174 opts: other options to use to parse the input expressions. 2175 2176 Returns: 2177 Select: the modified expression. 2178 """ 2179 return _apply_list_builder( 2180 *expressions, 2181 instance=self, 2182 arg="expressions", 2183 append=append, 2184 dialect=dialect, 2185 copy=copy, 2186 **opts, 2187 ) 2188 2189 def lateral(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 2190 """ 2191 Append to or set the LATERAL expressions. 2192 2193 Example: 2194 >>> Select().select("x").lateral("OUTER explode(y) tbl2 AS z").from_("tbl").sql() 2195 'SELECT x FROM tbl LATERAL VIEW OUTER EXPLODE(y) tbl2 AS z' 2196 2197 Args: 2198 *expressions (str | Expression): the SQL code strings to parse. 2199 If an `Expression` instance is passed, it will be used as-is. 2200 append (bool): if `True`, add to any existing expressions. 2201 Otherwise, this resets the expressions. 2202 dialect (str): the dialect used to parse the input expressions. 2203 copy (bool): if `False`, modify this expression instance in-place. 2204 opts (kwargs): other options to use to parse the input expressions. 2205 2206 Returns: 2207 Select: the modified expression. 2208 """ 2209 return _apply_list_builder( 2210 *expressions, 2211 instance=self, 2212 arg="laterals", 2213 append=append, 2214 into=Lateral, 2215 prefix="LATERAL VIEW", 2216 dialect=dialect, 2217 copy=copy, 2218 **opts, 2219 ) 2220 2221 def join( 2222 self, 2223 expression, 2224 on=None, 2225 using=None, 2226 append=True, 2227 join_type=None, 2228 join_alias=None, 2229 dialect=None, 2230 copy=True, 2231 **opts, 2232 ) -> Select: 2233 """ 2234 Append to or set the JOIN expressions. 2235 2236 Example: 2237 >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y").sql() 2238 'SELECT * FROM tbl JOIN tbl2 ON tbl1.y = tbl2.y' 2239 2240 >>> Select().select("1").from_("a").join("b", using=["x", "y", "z"]).sql() 2241 'SELECT 1 FROM a JOIN b USING (x, y, z)' 2242 2243 Use `join_type` to change the type of join: 2244 2245 >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y", join_type="left outer").sql() 2246 'SELECT * FROM tbl LEFT OUTER JOIN tbl2 ON tbl1.y = tbl2.y' 2247 2248 Args: 2249 expression (str | Expression): the SQL code string to parse. 2250 If an `Expression` instance is passed, it will be used as-is. 2251 on (str | Expression): optionally specify the join "on" criteria as a SQL string. 2252 If an `Expression` instance is passed, it will be used as-is. 2253 using (str | Expression): optionally specify the join "using" criteria as a SQL string. 2254 If an `Expression` instance is passed, it will be used as-is. 2255 append (bool): if `True`, add to any existing expressions. 2256 Otherwise, this resets the expressions. 2257 join_type (str): If set, alter the parsed join type 2258 dialect (str): the dialect used to parse the input expressions. 2259 copy (bool): if `False`, modify this expression instance in-place. 2260 opts (kwargs): other options to use to parse the input expressions. 2261 2262 Returns: 2263 Select: the modified expression. 2264 """ 2265 parse_args = {"dialect": dialect, **opts} 2266 2267 try: 2268 expression = maybe_parse(expression, into=Join, prefix="JOIN", **parse_args) 2269 except ParseError: 2270 expression = maybe_parse(expression, into=(Join, Expression), **parse_args) 2271 2272 join = expression if isinstance(expression, Join) else Join(this=expression) 2273 2274 if isinstance(join.this, Select): 2275 join.this.replace(join.this.subquery()) 2276 2277 if join_type: 2278 natural: t.Optional[Token] 2279 side: t.Optional[Token] 2280 kind: t.Optional[Token] 2281 2282 natural, side, kind = maybe_parse(join_type, into="JOIN_TYPE", **parse_args) # type: ignore 2283 2284 if natural: 2285 join.set("natural", True) 2286 if side: 2287 join.set("side", side.text) 2288 if kind: 2289 join.set("kind", kind.text) 2290 2291 if on: 2292 on = and_(*ensure_collection(on), dialect=dialect, **opts) 2293 join.set("on", on) 2294 2295 if using: 2296 join = _apply_list_builder( 2297 *ensure_collection(using), 2298 instance=join, 2299 arg="using", 2300 append=append, 2301 copy=copy, 2302 **opts, 2303 ) 2304 2305 if join_alias: 2306 join.set("this", alias_(join.this, join_alias, table=True)) 2307 return _apply_list_builder( 2308 join, 2309 instance=self, 2310 arg="joins", 2311 append=append, 2312 copy=copy, 2313 **opts, 2314 ) 2315 2316 def where(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 2317 """ 2318 Append to or set the WHERE expressions. 2319 2320 Example: 2321 >>> Select().select("x").from_("tbl").where("x = 'a' OR x < 'b'").sql() 2322 "SELECT x FROM tbl WHERE x = 'a' OR x < 'b'" 2323 2324 Args: 2325 *expressions (str | Expression): the SQL code strings to parse. 2326 If an `Expression` instance is passed, it will be used as-is. 2327 Multiple expressions are combined with an AND operator. 2328 append (bool): if `True`, AND the new expressions to any existing expression. 2329 Otherwise, this resets the expression. 2330 dialect (str): the dialect used to parse the input expressions. 2331 copy (bool): if `False`, modify this expression instance in-place. 2332 opts (kwargs): other options to use to parse the input expressions. 2333 2334 Returns: 2335 Select: the modified expression. 2336 """ 2337 return _apply_conjunction_builder( 2338 *expressions, 2339 instance=self, 2340 arg="where", 2341 append=append, 2342 into=Where, 2343 dialect=dialect, 2344 copy=copy, 2345 **opts, 2346 ) 2347 2348 def having(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 2349 """ 2350 Append to or set the HAVING expressions. 2351 2352 Example: 2353 >>> Select().select("x", "COUNT(y)").from_("tbl").group_by("x").having("COUNT(y) > 3").sql() 2354 'SELECT x, COUNT(y) FROM tbl GROUP BY x HAVING COUNT(y) > 3' 2355 2356 Args: 2357 *expressions (str | Expression): the SQL code strings to parse. 2358 If an `Expression` instance is passed, it will be used as-is. 2359 Multiple expressions are combined with an AND operator. 2360 append (bool): if `True`, AND the new expressions to any existing expression. 2361 Otherwise, this resets the expression. 2362 dialect (str): the dialect used to parse the input expressions. 2363 copy (bool): if `False`, modify this expression instance in-place. 2364 opts (kwargs): other options to use to parse the input expressions. 2365 2366 Returns: 2367 Select: the modified expression. 2368 """ 2369 return _apply_conjunction_builder( 2370 *expressions, 2371 instance=self, 2372 arg="having", 2373 append=append, 2374 into=Having, 2375 dialect=dialect, 2376 copy=copy, 2377 **opts, 2378 ) 2379 2380 def window(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 2381 return _apply_list_builder( 2382 *expressions, 2383 instance=self, 2384 arg="windows", 2385 append=append, 2386 into=Window, 2387 dialect=dialect, 2388 copy=copy, 2389 **opts, 2390 ) 2391 2392 def distinct(self, distinct=True, copy=True) -> Select: 2393 """ 2394 Set the OFFSET expression. 2395 2396 Example: 2397 >>> Select().from_("tbl").select("x").distinct().sql() 2398 'SELECT DISTINCT x FROM tbl' 2399 2400 Args: 2401 distinct (bool): whether the Select should be distinct 2402 copy (bool): if `False`, modify this expression instance in-place. 2403 2404 Returns: 2405 Select: the modified expression. 2406 """ 2407 instance = _maybe_copy(self, copy) 2408 instance.set("distinct", Distinct() if distinct else None) 2409 return instance 2410 2411 def ctas(self, table, properties=None, dialect=None, copy=True, **opts) -> Create: 2412 """ 2413 Convert this expression to a CREATE TABLE AS statement. 2414 2415 Example: 2416 >>> Select().select("*").from_("tbl").ctas("x").sql() 2417 'CREATE TABLE x AS SELECT * FROM tbl' 2418 2419 Args: 2420 table (str | Expression): the SQL code string to parse as the table name. 2421 If another `Expression` instance is passed, it will be used as-is. 2422 properties (dict): an optional mapping of table properties 2423 dialect (str): the dialect used to parse the input table. 2424 copy (bool): if `False`, modify this expression instance in-place. 2425 opts (kwargs): other options to use to parse the input table. 2426 2427 Returns: 2428 Create: the CREATE TABLE AS expression 2429 """ 2430 instance = _maybe_copy(self, copy) 2431 table_expression = maybe_parse( 2432 table, 2433 into=Table, 2434 dialect=dialect, 2435 **opts, 2436 ) 2437 properties_expression = None 2438 if properties: 2439 properties_expression = Properties.from_dict(properties) 2440 2441 return Create( 2442 this=table_expression, 2443 kind="table", 2444 expression=instance, 2445 properties=properties_expression, 2446 ) 2447 2448 def lock(self, update: bool = True, copy: bool = True) -> Select: 2449 """ 2450 Set the locking read mode for this expression. 2451 2452 Examples: 2453 >>> Select().select("x").from_("tbl").where("x = 'a'").lock().sql("mysql") 2454 "SELECT x FROM tbl WHERE x = 'a' FOR UPDATE" 2455 2456 >>> Select().select("x").from_("tbl").where("x = 'a'").lock(update=False).sql("mysql") 2457 "SELECT x FROM tbl WHERE x = 'a' FOR SHARE" 2458 2459 Args: 2460 update: if `True`, the locking type will be `FOR UPDATE`, else it will be `FOR SHARE`. 2461 copy: if `False`, modify this expression instance in-place. 2462 2463 Returns: 2464 The modified expression. 2465 """ 2466 2467 inst = _maybe_copy(self, copy) 2468 inst.set("lock", Lock(update=update)) 2469 2470 return inst 2471 2472 @property 2473 def named_selects(self) -> t.List[str]: 2474 return [e.output_name for e in self.expressions if e.alias_or_name] 2475 2476 @property 2477 def is_star(self) -> bool: 2478 return any(expression.is_star for expression in self.expressions) 2479 2480 @property 2481 def selects(self) -> t.List[Expression]: 2482 return self.expressions 2483 2484 2485class Subquery(DerivedTable, Unionable): 2486 arg_types = { 2487 "this": True, 2488 "alias": False, 2489 "with": False, 2490 **QUERY_MODIFIERS, 2491 } 2492 2493 def unnest(self): 2494 """ 2495 Returns the first non subquery. 2496 """ 2497 expression = self 2498 while isinstance(expression, Subquery): 2499 expression = expression.this 2500 return expression 2501 2502 @property 2503 def is_star(self) -> bool: 2504 return self.this.is_star 2505 2506 @property 2507 def output_name(self): 2508 return self.alias 2509 2510 2511class TableSample(Expression): 2512 arg_types = { 2513 "this": False, 2514 "method": False, 2515 "bucket_numerator": False, 2516 "bucket_denominator": False, 2517 "bucket_field": False, 2518 "percent": False, 2519 "rows": False, 2520 "size": False, 2521 "seed": False, 2522 } 2523 2524 2525class Tag(Expression): 2526 """Tags are used for generating arbitrary sql like SELECT <span>x</span>.""" 2527 2528 arg_types = { 2529 "this": False, 2530 "prefix": False, 2531 "postfix": False, 2532 } 2533 2534 2535class Pivot(Expression): 2536 arg_types = { 2537 "this": False, 2538 "alias": False, 2539 "expressions": True, 2540 "field": True, 2541 "unpivot": True, 2542 } 2543 2544 2545class Window(Expression): 2546 arg_types = { 2547 "this": True, 2548 "partition_by": False, 2549 "order": False, 2550 "spec": False, 2551 "alias": False, 2552 } 2553 2554 2555class WindowSpec(Expression): 2556 arg_types = { 2557 "kind": False, 2558 "start": False, 2559 "start_side": False, 2560 "end": False, 2561 "end_side": False, 2562 } 2563 2564 2565class Where(Expression): 2566 pass 2567 2568 2569class Star(Expression): 2570 arg_types = {"except": False, "replace": False} 2571 2572 @property 2573 def name(self) -> str: 2574 return "*" 2575 2576 @property 2577 def output_name(self): 2578 return self.name 2579 2580 2581class Parameter(Expression): 2582 arg_types = {"this": True, "wrapped": False} 2583 2584 2585class SessionParameter(Expression): 2586 arg_types = {"this": True, "kind": False} 2587 2588 2589class Placeholder(Expression): 2590 arg_types = {"this": False} 2591 2592 2593class Null(Condition): 2594 arg_types: t.Dict[str, t.Any] = {} 2595 2596 @property 2597 def name(self) -> str: 2598 return "NULL" 2599 2600 2601class Boolean(Condition): 2602 pass 2603 2604 2605class DataType(Expression): 2606 arg_types = { 2607 "this": True, 2608 "expressions": False, 2609 "nested": False, 2610 "values": False, 2611 "prefix": False, 2612 } 2613 2614 class Type(AutoName): 2615 CHAR = auto() 2616 NCHAR = auto() 2617 VARCHAR = auto() 2618 NVARCHAR = auto() 2619 TEXT = auto() 2620 MEDIUMTEXT = auto() 2621 LONGTEXT = auto() 2622 MEDIUMBLOB = auto() 2623 LONGBLOB = auto() 2624 BINARY = auto() 2625 VARBINARY = auto() 2626 INT = auto() 2627 TINYINT = auto() 2628 SMALLINT = auto() 2629 BIGINT = auto() 2630 FLOAT = auto() 2631 DOUBLE = auto() 2632 DECIMAL = auto() 2633 BOOLEAN = auto() 2634 JSON = auto() 2635 JSONB = auto() 2636 INTERVAL = auto() 2637 TIME = auto() 2638 TIMESTAMP = auto() 2639 TIMESTAMPTZ = auto() 2640 TIMESTAMPLTZ = auto() 2641 DATE = auto() 2642 DATETIME = auto() 2643 ARRAY = auto() 2644 MAP = auto() 2645 UUID = auto() 2646 GEOGRAPHY = auto() 2647 GEOMETRY = auto() 2648 STRUCT = auto() 2649 NULLABLE = auto() 2650 HLLSKETCH = auto() 2651 HSTORE = auto() 2652 SUPER = auto() 2653 SERIAL = auto() 2654 SMALLSERIAL = auto() 2655 BIGSERIAL = auto() 2656 XML = auto() 2657 UNIQUEIDENTIFIER = auto() 2658 MONEY = auto() 2659 SMALLMONEY = auto() 2660 ROWVERSION = auto() 2661 IMAGE = auto() 2662 VARIANT = auto() 2663 OBJECT = auto() 2664 INET = auto() 2665 NULL = auto() 2666 UNKNOWN = auto() # Sentinel value, useful for type annotation 2667 2668 TEXT_TYPES = { 2669 Type.CHAR, 2670 Type.NCHAR, 2671 Type.VARCHAR, 2672 Type.NVARCHAR, 2673 Type.TEXT, 2674 } 2675 2676 INTEGER_TYPES = { 2677 Type.INT, 2678 Type.TINYINT, 2679 Type.SMALLINT, 2680 Type.BIGINT, 2681 } 2682 2683 FLOAT_TYPES = { 2684 Type.FLOAT, 2685 Type.DOUBLE, 2686 } 2687 2688 NUMERIC_TYPES = {*INTEGER_TYPES, *FLOAT_TYPES} 2689 2690 TEMPORAL_TYPES = { 2691 Type.TIMESTAMP, 2692 Type.TIMESTAMPTZ, 2693 Type.TIMESTAMPLTZ, 2694 Type.DATE, 2695 Type.DATETIME, 2696 } 2697 2698 @classmethod 2699 def build( 2700 cls, dtype: str | DataType | DataType.Type, dialect: DialectType = None, **kwargs 2701 ) -> DataType: 2702 from sqlglot import parse_one 2703 2704 if isinstance(dtype, str): 2705 if dtype.upper() in cls.Type.__members__: 2706 data_type_exp: t.Optional[Expression] = DataType(this=DataType.Type[dtype.upper()]) 2707 else: 2708 data_type_exp = parse_one(dtype, read=dialect, into=DataType) 2709 if data_type_exp is None: 2710 raise ValueError(f"Unparsable data type value: {dtype}") 2711 elif isinstance(dtype, DataType.Type): 2712 data_type_exp = DataType(this=dtype) 2713 elif isinstance(dtype, DataType): 2714 return dtype 2715 else: 2716 raise ValueError(f"Invalid data type: {type(dtype)}. Expected str or DataType.Type") 2717 return DataType(**{**data_type_exp.args, **kwargs}) 2718 2719 def is_type(self, dtype: DataType.Type) -> bool: 2720 return self.this == dtype 2721 2722 2723# https://www.postgresql.org/docs/15/datatype-pseudo.html 2724class PseudoType(Expression): 2725 pass 2726 2727 2728class StructKwarg(Expression): 2729 arg_types = {"this": True, "expression": True} 2730 2731 2732# WHERE x <OP> EXISTS|ALL|ANY|SOME(SELECT ...) 2733class SubqueryPredicate(Predicate): 2734 pass 2735 2736 2737class All(SubqueryPredicate): 2738 pass 2739 2740 2741class Any(SubqueryPredicate): 2742 pass 2743 2744 2745class Exists(SubqueryPredicate): 2746 pass 2747 2748 2749# Commands to interact with the databases or engines. For most of the command 2750# expressions we parse whatever comes after the command's name as a string. 2751class Command(Expression): 2752 arg_types = {"this": True, "expression": False} 2753 2754 2755class Transaction(Expression): 2756 arg_types = {"this": False, "modes": False} 2757 2758 2759class Commit(Expression): 2760 arg_types = {"chain": False} 2761 2762 2763class Rollback(Expression): 2764 arg_types = {"savepoint": False} 2765 2766 2767class AlterTable(Expression): 2768 arg_types = {"this": True, "actions": True, "exists": False} 2769 2770 2771class AddConstraint(Expression): 2772 arg_types = {"this": False, "expression": False, "enforced": False} 2773 2774 2775class DropPartition(Expression): 2776 arg_types = {"expressions": True, "exists": False} 2777 2778 2779# Binary expressions like (ADD a b) 2780class Binary(Expression): 2781 arg_types = {"this": True, "expression": True} 2782 2783 @property 2784 def left(self): 2785 return self.this 2786 2787 @property 2788 def right(self): 2789 return self.expression 2790 2791 2792class Add(Binary): 2793 pass 2794 2795 2796class Connector(Binary, Condition): 2797 pass 2798 2799 2800class And(Connector): 2801 pass 2802 2803 2804class Or(Connector): 2805 pass 2806 2807 2808class BitwiseAnd(Binary): 2809 pass 2810 2811 2812class BitwiseLeftShift(Binary): 2813 pass 2814 2815 2816class BitwiseOr(Binary): 2817 pass 2818 2819 2820class BitwiseRightShift(Binary): 2821 pass 2822 2823 2824class BitwiseXor(Binary): 2825 pass 2826 2827 2828class Div(Binary): 2829 pass 2830 2831 2832class Dot(Binary): 2833 @property 2834 def name(self) -> str: 2835 return self.expression.name 2836 2837 2838class DPipe(Binary): 2839 pass 2840 2841 2842class EQ(Binary, Predicate): 2843 pass 2844 2845 2846class NullSafeEQ(Binary, Predicate): 2847 pass 2848 2849 2850class NullSafeNEQ(Binary, Predicate): 2851 pass 2852 2853 2854class Distance(Binary): 2855 pass 2856 2857 2858class Escape(Binary): 2859 pass 2860 2861 2862class Glob(Binary, Predicate): 2863 pass 2864 2865 2866class GT(Binary, Predicate): 2867 pass 2868 2869 2870class GTE(Binary, Predicate): 2871 pass 2872 2873 2874class ILike(Binary, Predicate): 2875 pass 2876 2877 2878class ILikeAny(Binary, Predicate): 2879 pass 2880 2881 2882class IntDiv(Binary): 2883 pass 2884 2885 2886class Is(Binary, Predicate): 2887 pass 2888 2889 2890class Kwarg(Binary): 2891 """Kwarg in special functions like func(kwarg => y).""" 2892 2893 2894class Like(Binary, Predicate): 2895 pass 2896 2897 2898class LikeAny(Binary, Predicate): 2899 pass 2900 2901 2902class LT(Binary, Predicate): 2903 pass 2904 2905 2906class LTE(Binary, Predicate): 2907 pass 2908 2909 2910class Mod(Binary): 2911 pass 2912 2913 2914class Mul(Binary): 2915 pass 2916 2917 2918class NEQ(Binary, Predicate): 2919 pass 2920 2921 2922class SimilarTo(Binary, Predicate): 2923 pass 2924 2925 2926class Slice(Binary): 2927 arg_types = {"this": False, "expression": False} 2928 2929 2930class Sub(Binary): 2931 pass 2932 2933 2934# Unary Expressions 2935# (NOT a) 2936class Unary(Expression): 2937 pass 2938 2939 2940class BitwiseNot(Unary): 2941 pass 2942 2943 2944class Not(Unary, Condition): 2945 pass 2946 2947 2948class Paren(Unary, Condition): 2949 arg_types = {"this": True, "with": False} 2950 2951 2952class Neg(Unary): 2953 pass 2954 2955 2956# Special Functions 2957class Alias(Expression): 2958 arg_types = {"this": True, "alias": False} 2959 2960 @property 2961 def output_name(self): 2962 return self.alias 2963 2964 2965class Aliases(Expression): 2966 arg_types = {"this": True, "expressions": True} 2967 2968 @property 2969 def aliases(self): 2970 return self.expressions 2971 2972 2973class AtTimeZone(Expression): 2974 arg_types = {"this": True, "zone": True} 2975 2976 2977class Between(Predicate): 2978 arg_types = {"this": True, "low": True, "high": True} 2979 2980 2981class Bracket(Condition): 2982 arg_types = {"this": True, "expressions": True} 2983 2984 2985class Distinct(Expression): 2986 arg_types = {"expressions": False, "on": False} 2987 2988 2989class In(Predicate): 2990 arg_types = { 2991 "this": True, 2992 "expressions": False, 2993 "query": False, 2994 "unnest": False, 2995 "field": False, 2996 "is_global": False, 2997 } 2998 2999 3000class TimeUnit(Expression): 3001 """Automatically converts unit arg into a var.""" 3002 3003 arg_types = {"unit": False} 3004 3005 def __init__(self, **args): 3006 unit = args.get("unit") 3007 if isinstance(unit, Column): 3008 args["unit"] = Var(this=unit.name) 3009 elif isinstance(unit, Week): 3010 unit.set("this", Var(this=unit.this.name)) 3011 super().__init__(**args) 3012 3013 3014class Interval(TimeUnit): 3015 arg_types = {"this": False, "unit": False} 3016 3017 3018class IgnoreNulls(Expression): 3019 pass 3020 3021 3022class RespectNulls(Expression): 3023 pass 3024 3025 3026# Functions 3027class Func(Condition): 3028 """ 3029 The base class for all function expressions. 3030 3031 Attributes: 3032 is_var_len_args (bool): if set to True the last argument defined in arg_types will be 3033 treated as a variable length argument and the argument's value will be stored as a list. 3034 _sql_names (list): determines the SQL name (1st item in the list) and aliases (subsequent items) 3035 for this function expression. These values are used to map this node to a name during parsing 3036 as well as to provide the function's name during SQL string generation. By default the SQL 3037 name is set to the expression's class name transformed to snake case. 3038 """ 3039 3040 is_var_len_args = False 3041 3042 @classmethod 3043 def from_arg_list(cls, args): 3044 if cls.is_var_len_args: 3045 all_arg_keys = list(cls.arg_types) 3046 # If this function supports variable length argument treat the last argument as such. 3047 non_var_len_arg_keys = all_arg_keys[:-1] if cls.is_var_len_args else all_arg_keys 3048 num_non_var = len(non_var_len_arg_keys) 3049 3050 args_dict = {arg_key: arg for arg, arg_key in zip(args, non_var_len_arg_keys)} 3051 args_dict[all_arg_keys[-1]] = args[num_non_var:] 3052 else: 3053 args_dict = {arg_key: arg for arg, arg_key in zip(args, cls.arg_types)} 3054 3055 return cls(**args_dict) 3056 3057 @classmethod 3058 def sql_names(cls): 3059 if cls is Func: 3060 raise NotImplementedError( 3061 "SQL name is only supported by concrete function implementations" 3062 ) 3063 if "_sql_names" not in cls.__dict__: 3064 cls._sql_names = [camel_to_snake_case(cls.__name__)] 3065 return cls._sql_names 3066 3067 @classmethod 3068 def sql_name(cls): 3069 return cls.sql_names()[0] 3070 3071 @classmethod 3072 def default_parser_mappings(cls): 3073 return {name: cls.from_arg_list for name in cls.sql_names()} 3074 3075 3076class AggFunc(Func): 3077 pass 3078 3079 3080class Abs(Func): 3081 pass 3082 3083 3084class Anonymous(Func): 3085 arg_types = {"this": True, "expressions": False} 3086 is_var_len_args = True 3087 3088 3089class ApproxDistinct(AggFunc): 3090 arg_types = {"this": True, "accuracy": False} 3091 3092 3093class Array(Func): 3094 arg_types = {"expressions": False} 3095 is_var_len_args = True 3096 3097 3098class GenerateSeries(Func): 3099 arg_types = {"start": True, "end": True, "step": False} 3100 3101 3102class ArrayAgg(AggFunc): 3103 pass 3104 3105 3106class ArrayAll(Func): 3107 arg_types = {"this": True, "expression": True} 3108 3109 3110class ArrayAny(Func): 3111 arg_types = {"this": True, "expression": True} 3112 3113 3114class ArrayConcat(Func): 3115 arg_types = {"this": True, "expressions": False} 3116 is_var_len_args = True 3117 3118 3119class ArrayContains(Func): 3120 arg_types = {"this": True, "expression": True} 3121 3122 3123class ArrayFilter(Func): 3124 arg_types = {"this": True, "expression": True} 3125 _sql_names = ["FILTER", "ARRAY_FILTER"] 3126 3127 3128class ArraySize(Func): 3129 arg_types = {"this": True, "expression": False} 3130 3131 3132class ArraySort(Func): 3133 arg_types = {"this": True, "expression": False} 3134 3135 3136class ArraySum(Func): 3137 pass 3138 3139 3140class ArrayUnionAgg(AggFunc): 3141 pass 3142 3143 3144class Avg(AggFunc): 3145 pass 3146 3147 3148class AnyValue(AggFunc): 3149 pass 3150 3151 3152class Case(Func): 3153 arg_types = {"this": False, "ifs": True, "default": False} 3154 3155 3156class Cast(Func): 3157 arg_types = {"this": True, "to": True} 3158 3159 @property 3160 def name(self) -> str: 3161 return self.this.name 3162 3163 @property 3164 def to(self): 3165 return self.args["to"] 3166 3167 @property 3168 def output_name(self): 3169 return self.name 3170 3171 def is_type(self, dtype: DataType.Type) -> bool: 3172 return self.to.is_type(dtype) 3173 3174 3175class Collate(Binary): 3176 pass 3177 3178 3179class TryCast(Cast): 3180 pass 3181 3182 3183class Ceil(Func): 3184 arg_types = {"this": True, "decimals": False} 3185 _sql_names = ["CEIL", "CEILING"] 3186 3187 3188class Coalesce(Func): 3189 arg_types = {"this": True, "expressions": False} 3190 is_var_len_args = True 3191 3192 3193class Concat(Func): 3194 arg_types = {"expressions": True} 3195 is_var_len_args = True 3196 3197 3198class ConcatWs(Concat): 3199 _sql_names = ["CONCAT_WS"] 3200 3201 3202class Count(AggFunc): 3203 arg_types = {"this": False} 3204 3205 3206class CurrentDate(Func): 3207 arg_types = {"this": False} 3208 3209 3210class CurrentDatetime(Func): 3211 arg_types = {"this": False} 3212 3213 3214class CurrentTime(Func): 3215 arg_types = {"this": False} 3216 3217 3218class CurrentTimestamp(Func): 3219 arg_types = {"this": False} 3220 3221 3222class DateAdd(Func, TimeUnit): 3223 arg_types = {"this": True, "expression": True, "unit": False} 3224 3225 3226class DateSub(Func, TimeUnit): 3227 arg_types = {"this": True, "expression": True, "unit": False} 3228 3229 3230class DateDiff(Func, TimeUnit): 3231 arg_types = {"this": True, "expression": True, "unit": False} 3232 3233 3234class DateTrunc(Func): 3235 arg_types = {"unit": True, "this": True, "zone": False} 3236 3237 3238class DatetimeAdd(Func, TimeUnit): 3239 arg_types = {"this": True, "expression": True, "unit": False} 3240 3241 3242class DatetimeSub(Func, TimeUnit): 3243 arg_types = {"this": True, "expression": True, "unit": False} 3244 3245 3246class DatetimeDiff(Func, TimeUnit): 3247 arg_types = {"this": True, "expression": True, "unit": False} 3248 3249 3250class DatetimeTrunc(Func, TimeUnit): 3251 arg_types = {"this": True, "unit": True, "zone": False} 3252 3253 3254class DayOfWeek(Func): 3255 _sql_names = ["DAY_OF_WEEK", "DAYOFWEEK"] 3256 3257 3258class DayOfMonth(Func): 3259 _sql_names = ["DAY_OF_MONTH", "DAYOFMONTH"] 3260 3261 3262class DayOfYear(Func): 3263 _sql_names = ["DAY_OF_YEAR", "DAYOFYEAR"] 3264 3265 3266class WeekOfYear(Func): 3267 _sql_names = ["WEEK_OF_YEAR", "WEEKOFYEAR"] 3268 3269 3270class LastDateOfMonth(Func): 3271 pass 3272 3273 3274class Extract(Func): 3275 arg_types = {"this": True, "expression": True} 3276 3277 3278class TimestampAdd(Func, TimeUnit): 3279 arg_types = {"this": True, "expression": True, "unit": False} 3280 3281 3282class TimestampSub(Func, TimeUnit): 3283 arg_types = {"this": True, "expression": True, "unit": False} 3284 3285 3286class TimestampDiff(Func, TimeUnit): 3287 arg_types = {"this": True, "expression": True, "unit": False} 3288 3289 3290class TimestampTrunc(Func, TimeUnit): 3291 arg_types = {"this": True, "unit": True, "zone": False} 3292 3293 3294class TimeAdd(Func, TimeUnit): 3295 arg_types = {"this": True, "expression": True, "unit": False} 3296 3297 3298class TimeSub(Func, TimeUnit): 3299 arg_types = {"this": True, "expression": True, "unit": False} 3300 3301 3302class TimeDiff(Func, TimeUnit): 3303 arg_types = {"this": True, "expression": True, "unit": False} 3304 3305 3306class TimeTrunc(Func, TimeUnit): 3307 arg_types = {"this": True, "unit": True, "zone": False} 3308 3309 3310class DateFromParts(Func): 3311 _sql_names = ["DATEFROMPARTS"] 3312 arg_types = {"year": True, "month": True, "day": True} 3313 3314 3315class DateStrToDate(Func): 3316 pass 3317 3318 3319class DateToDateStr(Func): 3320 pass 3321 3322 3323class DateToDi(Func): 3324 pass 3325 3326 3327class Day(Func): 3328 pass 3329 3330 3331class Decode(Func): 3332 arg_types = {"this": True, "charset": True, "replace": False} 3333 3334 3335class DiToDate(Func): 3336 pass 3337 3338 3339class Encode(Func): 3340 arg_types = {"this": True, "charset": True} 3341 3342 3343class Exp(Func): 3344 pass 3345 3346 3347class Explode(Func): 3348 pass 3349 3350 3351class Floor(Func): 3352 arg_types = {"this": True, "decimals": False} 3353 3354 3355class Greatest(Func): 3356 arg_types = {"this": True, "expressions": False} 3357 is_var_len_args = True 3358 3359 3360class GroupConcat(Func): 3361 arg_types = {"this": True, "separator": False} 3362 3363 3364class Hex(Func): 3365 pass 3366 3367 3368class If(Func): 3369 arg_types = {"this": True, "true": True, "false": False} 3370 3371 3372class IfNull(Func): 3373 arg_types = {"this": True, "expression": False} 3374 _sql_names = ["IFNULL", "NVL"] 3375 3376 3377class Initcap(Func): 3378 pass 3379 3380 3381class JSONBContains(Binary): 3382 _sql_names = ["JSONB_CONTAINS"] 3383 3384 3385class JSONExtract(Binary, Func): 3386 _sql_names = ["JSON_EXTRACT"] 3387 3388 3389class JSONExtractScalar(JSONExtract): 3390 _sql_names = ["JSON_EXTRACT_SCALAR"] 3391 3392 3393class JSONBExtract(JSONExtract): 3394 _sql_names = ["JSONB_EXTRACT"] 3395 3396 3397class JSONBExtractScalar(JSONExtract): 3398 _sql_names = ["JSONB_EXTRACT_SCALAR"] 3399 3400 3401class Least(Func): 3402 arg_types = {"this": True, "expressions": False} 3403 is_var_len_args = True 3404 3405 3406class Length(Func): 3407 pass 3408 3409 3410class Levenshtein(Func): 3411 arg_types = { 3412 "this": True, 3413 "expression": False, 3414 "ins_cost": False, 3415 "del_cost": False, 3416 "sub_cost": False, 3417 } 3418 3419 3420class Ln(Func): 3421 pass 3422 3423 3424class Log(Func): 3425 arg_types = {"this": True, "expression": False} 3426 3427 3428class Log2(Func): 3429 pass 3430 3431 3432class Log10(Func): 3433 pass 3434 3435 3436class LogicalOr(AggFunc): 3437 _sql_names = ["LOGICAL_OR", "BOOL_OR"] 3438 3439 3440class Lower(Func): 3441 _sql_names = ["LOWER", "LCASE"] 3442 3443 3444class Map(Func): 3445 arg_types = {"keys": False, "values": False} 3446 3447 3448class VarMap(Func): 3449 arg_types = {"keys": True, "values": True} 3450 is_var_len_args = True 3451 3452 3453class Matches(Func): 3454 """Oracle/Snowflake decode. 3455 https://docs.oracle.com/cd/B19306_01/server.102/b14200/functions040.htm 3456 Pattern matching MATCHES(value, search1, result1, ...searchN, resultN, else) 3457 """ 3458 3459 arg_types = {"this": True, "expressions": True} 3460 is_var_len_args = True 3461 3462 3463class Max(AggFunc): 3464 arg_types = {"this": True, "expression": False} 3465 3466 3467class Min(AggFunc): 3468 arg_types = {"this": True, "expression": False} 3469 3470 3471class Month(Func): 3472 pass 3473 3474 3475class Nvl2(Func): 3476 arg_types = {"this": True, "true": True, "false": False} 3477 3478 3479class Posexplode(Func): 3480 pass 3481 3482 3483class Pow(Binary, Func): 3484 _sql_names = ["POWER", "POW"] 3485 3486 3487class PercentileCont(AggFunc): 3488 pass 3489 3490 3491class PercentileDisc(AggFunc): 3492 pass 3493 3494 3495class Quantile(AggFunc): 3496 arg_types = {"this": True, "quantile": True} 3497 3498 3499# Clickhouse-specific: 3500# https://clickhouse.com/docs/en/sql-reference/aggregate-functions/reference/quantiles/#quantiles 3501class Quantiles(AggFunc): 3502 arg_types = {"parameters": True, "expressions": True} 3503 3504 3505class QuantileIf(AggFunc): 3506 arg_types = {"parameters": True, "expressions": True} 3507 3508 3509class ApproxQuantile(Quantile): 3510 arg_types = {"this": True, "quantile": True, "accuracy": False, "weight": False} 3511 3512 3513class ReadCSV(Func): 3514 _sql_names = ["READ_CSV"] 3515 is_var_len_args = True 3516 arg_types = {"this": True, "expressions": False} 3517 3518 3519class Reduce(Func): 3520 arg_types = {"this": True, "initial": True, "merge": True, "finish": False} 3521 3522 3523class RegexpExtract(Func): 3524 arg_types = { 3525 "this": True, 3526 "expression": True, 3527 "position": False, 3528 "occurrence": False, 3529 "group": False, 3530 } 3531 3532 3533class RegexpLike(Func): 3534 arg_types = {"this": True, "expression": True, "flag": False} 3535 3536 3537class RegexpILike(Func): 3538 arg_types = {"this": True, "expression": True, "flag": False} 3539 3540 3541class RegexpSplit(Func): 3542 arg_types = {"this": True, "expression": True} 3543 3544 3545class Repeat(Func): 3546 arg_types = {"this": True, "times": True} 3547 3548 3549class Round(Func): 3550 arg_types = {"this": True, "decimals": False} 3551 3552 3553class RowNumber(Func): 3554 arg_types: t.Dict[str, t.Any] = {} 3555 3556 3557class SafeDivide(Func): 3558 arg_types = {"this": True, "expression": True} 3559 3560 3561class SetAgg(AggFunc): 3562 pass 3563 3564 3565class SortArray(Func): 3566 arg_types = {"this": True, "asc": False} 3567 3568 3569class Split(Func): 3570 arg_types = {"this": True, "expression": True, "limit": False} 3571 3572 3573# Start may be omitted in the case of postgres 3574# https://www.postgresql.org/docs/9.1/functions-string.html @ Table 9-6 3575class Substring(Func): 3576 arg_types = {"this": True, "start": False, "length": False} 3577 3578 3579class StrPosition(Func): 3580 arg_types = { 3581 "this": True, 3582 "substr": True, 3583 "position": False, 3584 "instance": False, 3585 } 3586 3587 3588class StrToDate(Func): 3589 arg_types = {"this": True, "format": True} 3590 3591 3592class StrToTime(Func): 3593 arg_types = {"this": True, "format": True} 3594 3595 3596# Spark allows unix_timestamp() 3597# https://spark.apache.org/docs/3.1.3/api/python/reference/api/pyspark.sql.functions.unix_timestamp.html 3598class StrToUnix(Func): 3599 arg_types = {"this": False, "format": False} 3600 3601 3602class NumberToStr(Func): 3603 arg_types = {"this": True, "format": True} 3604 3605 3606class Struct(Func): 3607 arg_types = {"expressions": True} 3608 is_var_len_args = True 3609 3610 3611class StructExtract(Func): 3612 arg_types = {"this": True, "expression": True} 3613 3614 3615class Sum(AggFunc): 3616 pass 3617 3618 3619class Sqrt(Func): 3620 pass 3621 3622 3623class Stddev(AggFunc): 3624 pass 3625 3626 3627class StddevPop(AggFunc): 3628 pass 3629 3630 3631class StddevSamp(AggFunc): 3632 pass 3633 3634 3635class TimeToStr(Func): 3636 arg_types = {"this": True, "format": True} 3637 3638 3639class TimeToTimeStr(Func): 3640 pass 3641 3642 3643class TimeToUnix(Func): 3644 pass 3645 3646 3647class TimeStrToDate(Func): 3648 pass 3649 3650 3651class TimeStrToTime(Func): 3652 pass 3653 3654 3655class TimeStrToUnix(Func): 3656 pass 3657 3658 3659class Trim(Func): 3660 arg_types = { 3661 "this": True, 3662 "expression": False, 3663 "position": False, 3664 "collation": False, 3665 } 3666 3667 3668class TsOrDsAdd(Func, TimeUnit): 3669 arg_types = {"this": True, "expression": True, "unit": False} 3670 3671 3672class TsOrDsToDateStr(Func): 3673 pass 3674 3675 3676class TsOrDsToDate(Func): 3677 arg_types = {"this": True, "format": False} 3678 3679 3680class TsOrDiToDi(Func): 3681 pass 3682 3683 3684class Unhex(Func): 3685 pass 3686 3687 3688class UnixToStr(Func): 3689 arg_types = {"this": True, "format": False} 3690 3691 3692# https://prestodb.io/docs/current/functions/datetime.html 3693# presto has weird zone/hours/minutes 3694class UnixToTime(Func): 3695 arg_types = {"this": True, "scale": False, "zone": False, "hours": False, "minutes": False} 3696 3697 SECONDS = Literal.string("seconds") 3698 MILLIS = Literal.string("millis") 3699 MICROS = Literal.string("micros") 3700 3701 3702class UnixToTimeStr(Func): 3703 pass 3704 3705 3706class Upper(Func): 3707 _sql_names = ["UPPER", "UCASE"] 3708 3709 3710class Variance(AggFunc): 3711 _sql_names = ["VARIANCE", "VARIANCE_SAMP", "VAR_SAMP"] 3712 3713 3714class VariancePop(AggFunc): 3715 _sql_names = ["VARIANCE_POP", "VAR_POP"] 3716 3717 3718class Week(Func): 3719 arg_types = {"this": True, "mode": False} 3720 3721 3722class XMLTable(Func): 3723 arg_types = {"this": True, "passing": False, "columns": False, "by_ref": False} 3724 3725 3726class Year(Func): 3727 pass 3728 3729 3730class Use(Expression): 3731 arg_types = {"this": True, "kind": False} 3732 3733 3734class Merge(Expression): 3735 arg_types = {"this": True, "using": True, "on": True, "expressions": True} 3736 3737 3738class When(Func): 3739 arg_types = {"this": True, "then": True} 3740 3741 3742def _norm_args(expression): 3743 args = {} 3744 3745 for k, arg in expression.args.items(): 3746 if isinstance(arg, list): 3747 arg = [_norm_arg(a) for a in arg] 3748 if not arg: 3749 arg = None 3750 else: 3751 arg = _norm_arg(arg) 3752 3753 if arg is not None and arg is not False: 3754 args[k] = arg 3755 3756 return args 3757 3758 3759def _norm_arg(arg): 3760 return arg.lower() if isinstance(arg, str) else arg 3761 3762 3763ALL_FUNCTIONS = subclasses(__name__, Func, (AggFunc, Anonymous, Func)) 3764 3765 3766# Helpers 3767def maybe_parse( 3768 sql_or_expression: str | Expression, 3769 *, 3770 into: t.Optional[IntoType] = None, 3771 dialect: DialectType = None, 3772 prefix: t.Optional[str] = None, 3773 copy: bool = False, 3774 **opts, 3775) -> Expression: 3776 """Gracefully handle a possible string or expression. 3777 3778 Example: 3779 >>> maybe_parse("1") 3780 (LITERAL this: 1, is_string: False) 3781 >>> maybe_parse(to_identifier("x")) 3782 (IDENTIFIER this: x, quoted: False) 3783 3784 Args: 3785 sql_or_expression: the SQL code string or an expression 3786 into: the SQLGlot Expression to parse into 3787 dialect: the dialect used to parse the input expressions (in the case that an 3788 input expression is a SQL string). 3789 prefix: a string to prefix the sql with before it gets parsed 3790 (automatically includes a space) 3791 copy: whether or not to copy the expression. 3792 **opts: other options to use to parse the input expressions (again, in the case 3793 that an input expression is a SQL string). 3794 3795 Returns: 3796 Expression: the parsed or given expression. 3797 """ 3798 if isinstance(sql_or_expression, Expression): 3799 if copy: 3800 return sql_or_expression.copy() 3801 return sql_or_expression 3802 3803 import sqlglot 3804 3805 sql = str(sql_or_expression) 3806 if prefix: 3807 sql = f"{prefix} {sql}" 3808 return sqlglot.parse_one(sql, read=dialect, into=into, **opts) 3809 3810 3811def _maybe_copy(instance, copy=True): 3812 return instance.copy() if copy else instance 3813 3814 3815def _is_wrong_expression(expression, into): 3816 return isinstance(expression, Expression) and not isinstance(expression, into) 3817 3818 3819def _apply_builder( 3820 expression, 3821 instance, 3822 arg, 3823 copy=True, 3824 prefix=None, 3825 into=None, 3826 dialect=None, 3827 **opts, 3828): 3829 if _is_wrong_expression(expression, into): 3830 expression = into(this=expression) 3831 instance = _maybe_copy(instance, copy) 3832 expression = maybe_parse( 3833 sql_or_expression=expression, 3834 prefix=prefix, 3835 into=into, 3836 dialect=dialect, 3837 **opts, 3838 ) 3839 instance.set(arg, expression) 3840 return instance 3841 3842 3843def _apply_child_list_builder( 3844 *expressions, 3845 instance, 3846 arg, 3847 append=True, 3848 copy=True, 3849 prefix=None, 3850 into=None, 3851 dialect=None, 3852 properties=None, 3853 **opts, 3854): 3855 instance = _maybe_copy(instance, copy) 3856 parsed = [] 3857 for expression in expressions: 3858 if _is_wrong_expression(expression, into): 3859 expression = into(expressions=[expression]) 3860 expression = maybe_parse( 3861 expression, 3862 into=into, 3863 dialect=dialect, 3864 prefix=prefix, 3865 **opts, 3866 ) 3867 parsed.extend(expression.expressions) 3868 3869 existing = instance.args.get(arg) 3870 if append and existing: 3871 parsed = existing.expressions + parsed 3872 3873 child = into(expressions=parsed) 3874 for k, v in (properties or {}).items(): 3875 child.set(k, v) 3876 instance.set(arg, child) 3877 return instance 3878 3879 3880def _apply_list_builder( 3881 *expressions, 3882 instance, 3883 arg, 3884 append=True, 3885 copy=True, 3886 prefix=None, 3887 into=None, 3888 dialect=None, 3889 **opts, 3890): 3891 inst = _maybe_copy(instance, copy) 3892 3893 expressions = [ 3894 maybe_parse( 3895 sql_or_expression=expression, 3896 into=into, 3897 prefix=prefix, 3898 dialect=dialect, 3899 **opts, 3900 ) 3901 for expression in expressions 3902 ] 3903 3904 existing_expressions = inst.args.get(arg) 3905 if append and existing_expressions: 3906 expressions = existing_expressions + expressions 3907 3908 inst.set(arg, expressions) 3909 return inst 3910 3911 3912def _apply_conjunction_builder( 3913 *expressions, 3914 instance, 3915 arg, 3916 into=None, 3917 append=True, 3918 copy=True, 3919 dialect=None, 3920 **opts, 3921): 3922 expressions = [exp for exp in expressions if exp is not None and exp != ""] 3923 if not expressions: 3924 return instance 3925 3926 inst = _maybe_copy(instance, copy) 3927 3928 existing = inst.args.get(arg) 3929 if append and existing is not None: 3930 expressions = [existing.this if into else existing] + list(expressions) 3931 3932 node = and_(*expressions, dialect=dialect, **opts) 3933 3934 inst.set(arg, into(this=node) if into else node) 3935 return inst 3936 3937 3938def _combine(expressions, operator, dialect=None, **opts): 3939 expressions = [condition(expression, dialect=dialect, **opts) for expression in expressions] 3940 this = expressions[0] 3941 if expressions[1:]: 3942 this = _wrap_operator(this) 3943 for expression in expressions[1:]: 3944 this = operator(this=this, expression=_wrap_operator(expression)) 3945 return this 3946 3947 3948def _wrap_operator(expression): 3949 if isinstance(expression, (And, Or, Not)): 3950 expression = Paren(this=expression) 3951 return expression 3952 3953 3954def union(left, right, distinct=True, dialect=None, **opts): 3955 """ 3956 Initializes a syntax tree from one UNION expression. 3957 3958 Example: 3959 >>> union("SELECT * FROM foo", "SELECT * FROM bla").sql() 3960 'SELECT * FROM foo UNION SELECT * FROM bla' 3961 3962 Args: 3963 left (str | Expression): the SQL code string corresponding to the left-hand side. 3964 If an `Expression` instance is passed, it will be used as-is. 3965 right (str | Expression): the SQL code string corresponding to the right-hand side. 3966 If an `Expression` instance is passed, it will be used as-is. 3967 distinct (bool): set the DISTINCT flag if and only if this is true. 3968 dialect (str): the dialect used to parse the input expression. 3969 opts (kwargs): other options to use to parse the input expressions. 3970 Returns: 3971 Union: the syntax tree for the UNION expression. 3972 """ 3973 left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts) 3974 right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts) 3975 3976 return Union(this=left, expression=right, distinct=distinct) 3977 3978 3979def intersect(left, right, distinct=True, dialect=None, **opts): 3980 """ 3981 Initializes a syntax tree from one INTERSECT expression. 3982 3983 Example: 3984 >>> intersect("SELECT * FROM foo", "SELECT * FROM bla").sql() 3985 'SELECT * FROM foo INTERSECT SELECT * FROM bla' 3986 3987 Args: 3988 left (str | Expression): the SQL code string corresponding to the left-hand side. 3989 If an `Expression` instance is passed, it will be used as-is. 3990 right (str | Expression): the SQL code string corresponding to the right-hand side. 3991 If an `Expression` instance is passed, it will be used as-is. 3992 distinct (bool): set the DISTINCT flag if and only if this is true. 3993 dialect (str): the dialect used to parse the input expression. 3994 opts (kwargs): other options to use to parse the input expressions. 3995 Returns: 3996 Intersect: the syntax tree for the INTERSECT expression. 3997 """ 3998 left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts) 3999 right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts) 4000 4001 return Intersect(this=left, expression=right, distinct=distinct) 4002 4003 4004def except_(left, right, distinct=True, dialect=None, **opts): 4005 """ 4006 Initializes a syntax tree from one EXCEPT expression. 4007 4008 Example: 4009 >>> except_("SELECT * FROM foo", "SELECT * FROM bla").sql() 4010 'SELECT * FROM foo EXCEPT SELECT * FROM bla' 4011 4012 Args: 4013 left (str | Expression): the SQL code string corresponding to the left-hand side. 4014 If an `Expression` instance is passed, it will be used as-is. 4015 right (str | Expression): the SQL code string corresponding to the right-hand side. 4016 If an `Expression` instance is passed, it will be used as-is. 4017 distinct (bool): set the DISTINCT flag if and only if this is true. 4018 dialect (str): the dialect used to parse the input expression. 4019 opts (kwargs): other options to use to parse the input expressions. 4020 Returns: 4021 Except: the syntax tree for the EXCEPT statement. 4022 """ 4023 left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts) 4024 right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts) 4025 4026 return Except(this=left, expression=right, distinct=distinct) 4027 4028 4029def select(*expressions: str | Expression, dialect: DialectType = None, **opts) -> Select: 4030 """ 4031 Initializes a syntax tree from one or multiple SELECT expressions. 4032 4033 Example: 4034 >>> select("col1", "col2").from_("tbl").sql() 4035 'SELECT col1, col2 FROM tbl' 4036 4037 Args: 4038 *expressions: the SQL code string to parse as the expressions of a 4039 SELECT statement. If an Expression instance is passed, this is used as-is. 4040 dialect: the dialect used to parse the input expressions (in the case that an 4041 input expression is a SQL string). 4042 **opts: other options to use to parse the input expressions (again, in the case 4043 that an input expression is a SQL string). 4044 4045 Returns: 4046 Select: the syntax tree for the SELECT statement. 4047 """ 4048 return Select().select(*expressions, dialect=dialect, **opts) 4049 4050 4051def from_(*expressions, dialect=None, **opts) -> Select: 4052 """ 4053 Initializes a syntax tree from a FROM expression. 4054 4055 Example: 4056 >>> from_("tbl").select("col1", "col2").sql() 4057 'SELECT col1, col2 FROM tbl' 4058 4059 Args: 4060 *expressions (str | Expression): the SQL code string to parse as the FROM expressions of a 4061 SELECT statement. If an Expression instance is passed, this is used as-is. 4062 dialect (str): the dialect used to parse the input expression (in the case that the 4063 input expression is a SQL string). 4064 **opts: other options to use to parse the input expressions (again, in the case 4065 that the input expression is a SQL string). 4066 4067 Returns: 4068 Select: the syntax tree for the SELECT statement. 4069 """ 4070 return Select().from_(*expressions, dialect=dialect, **opts) 4071 4072 4073def update(table, properties, where=None, from_=None, dialect=None, **opts) -> Update: 4074 """ 4075 Creates an update statement. 4076 4077 Example: 4078 >>> update("my_table", {"x": 1, "y": "2", "z": None}, from_="baz", where="id > 1").sql() 4079 "UPDATE my_table SET x = 1, y = '2', z = NULL FROM baz WHERE id > 1" 4080 4081 Args: 4082 *properties (Dict[str, Any]): dictionary of properties to set which are 4083 auto converted to sql objects eg None -> NULL 4084 where (str): sql conditional parsed into a WHERE statement 4085 from_ (str): sql statement parsed into a FROM statement 4086 dialect (str): the dialect used to parse the input expressions. 4087 **opts: other options to use to parse the input expressions. 4088 4089 Returns: 4090 Update: the syntax tree for the UPDATE statement. 4091 """ 4092 update = Update(this=maybe_parse(table, into=Table, dialect=dialect)) 4093 update.set( 4094 "expressions", 4095 [ 4096 EQ(this=maybe_parse(k, dialect=dialect, **opts), expression=convert(v)) 4097 for k, v in properties.items() 4098 ], 4099 ) 4100 if from_: 4101 update.set( 4102 "from", 4103 maybe_parse(from_, into=From, dialect=dialect, prefix="FROM", **opts), 4104 ) 4105 if isinstance(where, Condition): 4106 where = Where(this=where) 4107 if where: 4108 update.set( 4109 "where", 4110 maybe_parse(where, into=Where, dialect=dialect, prefix="WHERE", **opts), 4111 ) 4112 return update 4113 4114 4115def delete(table, where=None, dialect=None, **opts) -> Delete: 4116 """ 4117 Builds a delete statement. 4118 4119 Example: 4120 >>> delete("my_table", where="id > 1").sql() 4121 'DELETE FROM my_table WHERE id > 1' 4122 4123 Args: 4124 where (str|Condition): sql conditional parsed into a WHERE statement 4125 dialect (str): the dialect used to parse the input expressions. 4126 **opts: other options to use to parse the input expressions. 4127 4128 Returns: 4129 Delete: the syntax tree for the DELETE statement. 4130 """ 4131 return Delete( 4132 this=maybe_parse(table, into=Table, dialect=dialect, **opts), 4133 where=Where(this=where) 4134 if isinstance(where, Condition) 4135 else maybe_parse(where, into=Where, dialect=dialect, prefix="WHERE", **opts), 4136 ) 4137 4138 4139def condition(expression, dialect=None, **opts) -> Condition: 4140 """ 4141 Initialize a logical condition expression. 4142 4143 Example: 4144 >>> condition("x=1").sql() 4145 'x = 1' 4146 4147 This is helpful for composing larger logical syntax trees: 4148 >>> where = condition("x=1") 4149 >>> where = where.and_("y=1") 4150 >>> Select().from_("tbl").select("*").where(where).sql() 4151 'SELECT * FROM tbl WHERE x = 1 AND y = 1' 4152 4153 Args: 4154 *expression (str | Expression): the SQL code string to parse. 4155 If an Expression instance is passed, this is used as-is. 4156 dialect (str): the dialect used to parse the input expression (in the case that the 4157 input expression is a SQL string). 4158 **opts: other options to use to parse the input expressions (again, in the case 4159 that the input expression is a SQL string). 4160 4161 Returns: 4162 Condition: the expression 4163 """ 4164 return maybe_parse( # type: ignore 4165 expression, 4166 into=Condition, 4167 dialect=dialect, 4168 **opts, 4169 ) 4170 4171 4172def and_(*expressions, dialect=None, **opts) -> And: 4173 """ 4174 Combine multiple conditions with an AND logical operator. 4175 4176 Example: 4177 >>> and_("x=1", and_("y=1", "z=1")).sql() 4178 'x = 1 AND (y = 1 AND z = 1)' 4179 4180 Args: 4181 *expressions (str | Expression): the SQL code strings to parse. 4182 If an Expression instance is passed, this is used as-is. 4183 dialect (str): the dialect used to parse the input expression. 4184 **opts: other options to use to parse the input expressions. 4185 4186 Returns: 4187 And: the new condition 4188 """ 4189 return _combine(expressions, And, dialect, **opts) 4190 4191 4192def or_(*expressions, dialect=None, **opts) -> Or: 4193 """ 4194 Combine multiple conditions with an OR logical operator. 4195 4196 Example: 4197 >>> or_("x=1", or_("y=1", "z=1")).sql() 4198 'x = 1 OR (y = 1 OR z = 1)' 4199 4200 Args: 4201 *expressions (str | Expression): the SQL code strings to parse. 4202 If an Expression instance is passed, this is used as-is. 4203 dialect (str): the dialect used to parse the input expression. 4204 **opts: other options to use to parse the input expressions. 4205 4206 Returns: 4207 Or: the new condition 4208 """ 4209 return _combine(expressions, Or, dialect, **opts) 4210 4211 4212def not_(expression, dialect=None, **opts) -> Not: 4213 """ 4214 Wrap a condition with a NOT operator. 4215 4216 Example: 4217 >>> not_("this_suit='black'").sql() 4218 "NOT this_suit = 'black'" 4219 4220 Args: 4221 expression (str | Expression): the SQL code strings to parse. 4222 If an Expression instance is passed, this is used as-is. 4223 dialect (str): the dialect used to parse the input expression. 4224 **opts: other options to use to parse the input expressions. 4225 4226 Returns: 4227 Not: the new condition 4228 """ 4229 this = condition( 4230 expression, 4231 dialect=dialect, 4232 **opts, 4233 ) 4234 return Not(this=_wrap_operator(this)) 4235 4236 4237def paren(expression) -> Paren: 4238 return Paren(this=expression) 4239 4240 4241SAFE_IDENTIFIER_RE = re.compile(r"^[_a-zA-Z][\w]*$") 4242 4243 4244@t.overload 4245def to_identifier(name: None, quoted: t.Optional[bool] = None) -> None: 4246 ... 4247 4248 4249@t.overload 4250def to_identifier(name: str | Identifier, quoted: t.Optional[bool] = None) -> Identifier: 4251 ... 4252 4253 4254def to_identifier(name, quoted=None): 4255 """Builds an identifier. 4256 4257 Args: 4258 name: The name to turn into an identifier. 4259 quoted: Whether or not force quote the identifier. 4260 4261 Returns: 4262 The identifier ast node. 4263 """ 4264 4265 if name is None: 4266 return None 4267 4268 if isinstance(name, Identifier): 4269 identifier = name 4270 elif isinstance(name, str): 4271 identifier = Identifier( 4272 this=name, 4273 quoted=not re.match(SAFE_IDENTIFIER_RE, name) if quoted is None else quoted, 4274 ) 4275 else: 4276 raise ValueError(f"Name needs to be a string or an Identifier, got: {name.__class__}") 4277 return identifier 4278 4279 4280INTERVAL_STRING_RE = re.compile(r"\s*([0-9]+)\s*([a-zA-Z]+)\s*") 4281 4282 4283def to_interval(interval: str | Literal) -> Interval: 4284 """Builds an interval expression from a string like '1 day' or '5 months'.""" 4285 if isinstance(interval, Literal): 4286 if not interval.is_string: 4287 raise ValueError("Invalid interval string.") 4288 4289 interval = interval.this 4290 4291 interval_parts = INTERVAL_STRING_RE.match(interval) # type: ignore 4292 4293 if not interval_parts: 4294 raise ValueError("Invalid interval string.") 4295 4296 return Interval( 4297 this=Literal.string(interval_parts.group(1)), 4298 unit=Var(this=interval_parts.group(2)), 4299 ) 4300 4301 4302@t.overload 4303def to_table(sql_path: str | Table, **kwargs) -> Table: 4304 ... 4305 4306 4307@t.overload 4308def to_table(sql_path: None, **kwargs) -> None: 4309 ... 4310 4311 4312def to_table(sql_path: t.Optional[str | Table], **kwargs) -> t.Optional[Table]: 4313 """ 4314 Create a table expression from a `[catalog].[schema].[table]` sql path. Catalog and schema are optional. 4315 If a table is passed in then that table is returned. 4316 4317 Args: 4318 sql_path: a `[catalog].[schema].[table]` string. 4319 4320 Returns: 4321 A table expression. 4322 """ 4323 if sql_path is None or isinstance(sql_path, Table): 4324 return sql_path 4325 if not isinstance(sql_path, str): 4326 raise ValueError(f"Invalid type provided for a table: {type(sql_path)}") 4327 4328 catalog, db, table_name = (to_identifier(x) for x in split_num_words(sql_path, ".", 3)) 4329 return Table(this=table_name, db=db, catalog=catalog, **kwargs) 4330 4331 4332def to_column(sql_path: str | Column, **kwargs) -> Column: 4333 """ 4334 Create a column from a `[table].[column]` sql path. Schema is optional. 4335 4336 If a column is passed in then that column is returned. 4337 4338 Args: 4339 sql_path: `[table].[column]` string 4340 Returns: 4341 Table: A column expression 4342 """ 4343 if sql_path is None or isinstance(sql_path, Column): 4344 return sql_path 4345 if not isinstance(sql_path, str): 4346 raise ValueError(f"Invalid type provided for column: {type(sql_path)}") 4347 table_name, column_name = (to_identifier(x) for x in split_num_words(sql_path, ".", 2)) 4348 return Column(this=column_name, table=table_name, **kwargs) 4349 4350 4351def alias_( 4352 expression: str | Expression, 4353 alias: str | Identifier, 4354 table: bool | t.Sequence[str | Identifier] = False, 4355 quoted: t.Optional[bool] = None, 4356 dialect: DialectType = None, 4357 **opts, 4358): 4359 """Create an Alias expression. 4360 4361 Example: 4362 >>> alias_('foo', 'bar').sql() 4363 'foo AS bar' 4364 4365 >>> alias_('(select 1, 2)', 'bar', table=['a', 'b']).sql() 4366 '(SELECT 1, 2) AS bar(a, b)' 4367 4368 Args: 4369 expression: the SQL code strings to parse. 4370 If an Expression instance is passed, this is used as-is. 4371 alias: the alias name to use. If the name has 4372 special characters it is quoted. 4373 table: Whether or not to create a table alias, can also be a list of columns. 4374 quoted: whether or not to quote the alias 4375 dialect: the dialect used to parse the input expression. 4376 **opts: other options to use to parse the input expressions. 4377 4378 Returns: 4379 Alias: the aliased expression 4380 """ 4381 exp = maybe_parse(expression, dialect=dialect, **opts) 4382 alias = to_identifier(alias, quoted=quoted) 4383 4384 if table: 4385 table_alias = TableAlias(this=alias) 4386 exp.set("alias", table_alias) 4387 4388 if not isinstance(table, bool): 4389 for column in table: 4390 table_alias.append("columns", to_identifier(column, quoted=quoted)) 4391 4392 return exp 4393 4394 # We don't set the "alias" arg for Window expressions, because that would add an IDENTIFIER node in 4395 # the AST, representing a "named_window" [1] construct (eg. bigquery). What we want is an ALIAS node 4396 # for the complete Window expression. 4397 # 4398 # [1]: https://cloud.google.com/bigquery/docs/reference/standard-sql/window-function-calls 4399 4400 if "alias" in exp.arg_types and not isinstance(exp, Window): 4401 exp = exp.copy() 4402 exp.set("alias", alias) 4403 return exp 4404 return Alias(this=exp, alias=alias) 4405 4406 4407def subquery(expression, alias=None, dialect=None, **opts): 4408 """ 4409 Build a subquery expression. 4410 4411 Example: 4412 >>> subquery('select x from tbl', 'bar').select('x').sql() 4413 'SELECT x FROM (SELECT x FROM tbl) AS bar' 4414 4415 Args: 4416 expression (str | Expression): the SQL code strings to parse. 4417 If an Expression instance is passed, this is used as-is. 4418 alias (str | Expression): the alias name to use. 4419 dialect (str): the dialect used to parse the input expression. 4420 **opts: other options to use to parse the input expressions. 4421 4422 Returns: 4423 Select: a new select with the subquery expression included 4424 """ 4425 4426 expression = maybe_parse(expression, dialect=dialect, **opts).subquery(alias) 4427 return Select().from_(expression, dialect=dialect, **opts) 4428 4429 4430def column( 4431 col: str | Identifier, 4432 table: t.Optional[str | Identifier] = None, 4433 schema: t.Optional[str | Identifier] = None, 4434 quoted: t.Optional[bool] = None, 4435) -> Column: 4436 """ 4437 Build a Column. 4438 4439 Args: 4440 col: column name 4441 table: table name 4442 schema: schema name 4443 quoted: whether or not to force quote each part 4444 Returns: 4445 Column: column instance 4446 """ 4447 return Column( 4448 this=to_identifier(col, quoted=quoted), 4449 table=to_identifier(table, quoted=quoted), 4450 schema=to_identifier(schema, quoted=quoted), 4451 ) 4452 4453 4454def cast(expression: str | Expression, to: str | DataType | DataType.Type, **opts) -> Cast: 4455 """Cast an expression to a data type. 4456 4457 Example: 4458 >>> cast('x + 1', 'int').sql() 4459 'CAST(x + 1 AS INT)' 4460 4461 Args: 4462 expression: The expression to cast. 4463 to: The datatype to cast to. 4464 4465 Returns: 4466 A cast node. 4467 """ 4468 expression = maybe_parse(expression, **opts) 4469 return Cast(this=expression, to=DataType.build(to, **opts)) 4470 4471 4472def table_(table, db=None, catalog=None, quoted=None, alias=None) -> Table: 4473 """Build a Table. 4474 4475 Args: 4476 table (str | Expression): column name 4477 db (str | Expression): db name 4478 catalog (str | Expression): catalog name 4479 4480 Returns: 4481 Table: table instance 4482 """ 4483 return Table( 4484 this=to_identifier(table, quoted=quoted), 4485 db=to_identifier(db, quoted=quoted), 4486 catalog=to_identifier(catalog, quoted=quoted), 4487 alias=TableAlias(this=to_identifier(alias)) if alias else None, 4488 ) 4489 4490 4491def values( 4492 values: t.Iterable[t.Tuple[t.Any, ...]], 4493 alias: t.Optional[str] = None, 4494 columns: t.Optional[t.Iterable[str] | t.Dict[str, DataType]] = None, 4495) -> Values: 4496 """Build VALUES statement. 4497 4498 Example: 4499 >>> values([(1, '2')]).sql() 4500 "VALUES (1, '2')" 4501 4502 Args: 4503 values: values statements that will be converted to SQL 4504 alias: optional alias 4505 columns: Optional list of ordered column names or ordered dictionary of column names to types. 4506 If either are provided then an alias is also required. 4507 If a dictionary is provided then the first column of the values will be casted to the expected type 4508 in order to help with type inference. 4509 4510 Returns: 4511 Values: the Values expression object 4512 """ 4513 if columns and not alias: 4514 raise ValueError("Alias is required when providing columns") 4515 table_alias = ( 4516 TableAlias(this=to_identifier(alias), columns=[to_identifier(x) for x in columns]) 4517 if columns 4518 else TableAlias(this=to_identifier(alias) if alias else None) 4519 ) 4520 expressions = [convert(tup) for tup in values] 4521 if columns and isinstance(columns, dict): 4522 types = list(columns.values()) 4523 expressions[0].set( 4524 "expressions", 4525 [cast(x, types[i]) for i, x in enumerate(expressions[0].expressions)], 4526 ) 4527 return Values( 4528 expressions=expressions, 4529 alias=table_alias, 4530 ) 4531 4532 4533def var(name: t.Optional[str | Expression]) -> Var: 4534 """Build a SQL variable. 4535 4536 Example: 4537 >>> repr(var('x')) 4538 '(VAR this: x)' 4539 4540 >>> repr(var(column('x', table='y'))) 4541 '(VAR this: x)' 4542 4543 Args: 4544 name: The name of the var or an expression who's name will become the var. 4545 4546 Returns: 4547 The new variable node. 4548 """ 4549 if not name: 4550 raise ValueError(f"Cannot convert empty name into var.") 4551 4552 if isinstance(name, Expression): 4553 name = name.name 4554 return Var(this=name) 4555 4556 4557def rename_table(old_name: str | Table, new_name: str | Table) -> AlterTable: 4558 """Build ALTER TABLE... RENAME... expression 4559 4560 Args: 4561 old_name: The old name of the table 4562 new_name: The new name of the table 4563 4564 Returns: 4565 Alter table expression 4566 """ 4567 old_table = to_table(old_name) 4568 new_table = to_table(new_name) 4569 return AlterTable( 4570 this=old_table, 4571 actions=[ 4572 RenameTable(this=new_table), 4573 ], 4574 ) 4575 4576 4577def convert(value) -> Expression: 4578 """Convert a python value into an expression object. 4579 4580 Raises an error if a conversion is not possible. 4581 4582 Args: 4583 value (Any): a python object 4584 4585 Returns: 4586 Expression: the equivalent expression object 4587 """ 4588 if isinstance(value, Expression): 4589 return value 4590 if value is None: 4591 return NULL 4592 if isinstance(value, bool): 4593 return Boolean(this=value) 4594 if isinstance(value, str): 4595 return Literal.string(value) 4596 if isinstance(value, float) and math.isnan(value): 4597 return NULL 4598 if isinstance(value, numbers.Number): 4599 return Literal.number(value) 4600 if isinstance(value, tuple): 4601 return Tuple(expressions=[convert(v) for v in value]) 4602 if isinstance(value, list): 4603 return Array(expressions=[convert(v) for v in value]) 4604 if isinstance(value, dict): 4605 return Map( 4606 keys=[convert(k) for k in value], 4607 values=[convert(v) for v in value.values()], 4608 ) 4609 if isinstance(value, datetime.datetime): 4610 datetime_literal = Literal.string( 4611 (value if value.tzinfo else value.replace(tzinfo=datetime.timezone.utc)).isoformat() 4612 ) 4613 return TimeStrToTime(this=datetime_literal) 4614 if isinstance(value, datetime.date): 4615 date_literal = Literal.string(value.strftime("%Y-%m-%d")) 4616 return DateStrToDate(this=date_literal) 4617 raise ValueError(f"Cannot convert {value}") 4618 4619 4620def replace_children(expression, fun): 4621 """ 4622 Replace children of an expression with the result of a lambda fun(child) -> exp. 4623 """ 4624 for k, v in expression.args.items(): 4625 is_list_arg = isinstance(v, list) 4626 4627 child_nodes = v if is_list_arg else [v] 4628 new_child_nodes = [] 4629 4630 for cn in child_nodes: 4631 if isinstance(cn, Expression): 4632 for child_node in ensure_collection(fun(cn)): 4633 new_child_nodes.append(child_node) 4634 child_node.parent = expression 4635 child_node.arg_key = k 4636 else: 4637 new_child_nodes.append(cn) 4638 4639 expression.args[k] = new_child_nodes if is_list_arg else seq_get(new_child_nodes, 0) 4640 4641 4642def column_table_names(expression): 4643 """ 4644 Return all table names referenced through columns in an expression. 4645 4646 Example: 4647 >>> import sqlglot 4648 >>> column_table_names(sqlglot.parse_one("a.b AND c.d AND c.e")) 4649 ['c', 'a'] 4650 4651 Args: 4652 expression (sqlglot.Expression): expression to find table names 4653 4654 Returns: 4655 list: A list of unique names 4656 """ 4657 return list(dict.fromkeys(column.table for column in expression.find_all(Column))) 4658 4659 4660def table_name(table) -> str: 4661 """Get the full name of a table as a string. 4662 4663 Args: 4664 table (exp.Table | str): table expression node or string. 4665 4666 Examples: 4667 >>> from sqlglot import exp, parse_one 4668 >>> table_name(parse_one("select * from a.b.c").find(exp.Table)) 4669 'a.b.c' 4670 4671 Returns: 4672 The table name. 4673 """ 4674 4675 table = maybe_parse(table, into=Table) 4676 4677 if not table: 4678 raise ValueError(f"Cannot parse {table}") 4679 4680 return ".".join( 4681 part 4682 for part in ( 4683 table.text("catalog"), 4684 table.text("db"), 4685 table.name, 4686 ) 4687 if part 4688 ) 4689 4690 4691def replace_tables(expression, mapping): 4692 """Replace all tables in expression according to the mapping. 4693 4694 Args: 4695 expression (sqlglot.Expression): expression node to be transformed and replaced. 4696 mapping (Dict[str, str]): mapping of table names. 4697 4698 Examples: 4699 >>> from sqlglot import exp, parse_one 4700 >>> replace_tables(parse_one("select * from a.b"), {"a.b": "c"}).sql() 4701 'SELECT * FROM c' 4702 4703 Returns: 4704 The mapped expression. 4705 """ 4706 4707 def _replace_tables(node): 4708 if isinstance(node, Table): 4709 new_name = mapping.get(table_name(node)) 4710 if new_name: 4711 return to_table( 4712 new_name, 4713 **{k: v for k, v in node.args.items() if k not in ("this", "db", "catalog")}, 4714 ) 4715 return node 4716 4717 return expression.transform(_replace_tables) 4718 4719 4720def replace_placeholders(expression, *args, **kwargs): 4721 """Replace placeholders in an expression. 4722 4723 Args: 4724 expression (sqlglot.Expression): expression node to be transformed and replaced. 4725 args: positional names that will substitute unnamed placeholders in the given order. 4726 kwargs: keyword arguments that will substitute named placeholders. 4727 4728 Examples: 4729 >>> from sqlglot import exp, parse_one 4730 >>> replace_placeholders( 4731 ... parse_one("select * from :tbl where ? = ?"), "a", "b", tbl="foo" 4732 ... ).sql() 4733 'SELECT * FROM foo WHERE a = b' 4734 4735 Returns: 4736 The mapped expression. 4737 """ 4738 4739 def _replace_placeholders(node, args, **kwargs): 4740 if isinstance(node, Placeholder): 4741 if node.name: 4742 new_name = kwargs.get(node.name) 4743 if new_name: 4744 return to_identifier(new_name) 4745 else: 4746 try: 4747 return to_identifier(next(args)) 4748 except StopIteration: 4749 pass 4750 return node 4751 4752 return expression.transform(_replace_placeholders, iter(args), **kwargs) 4753 4754 4755def expand(expression: Expression, sources: t.Dict[str, Subqueryable], copy=True) -> Expression: 4756 """Transforms an expression by expanding all referenced sources into subqueries. 4757 4758 Examples: 4759 >>> from sqlglot import parse_one 4760 >>> expand(parse_one("select * from x AS z"), {"x": parse_one("select * from y")}).sql() 4761 'SELECT * FROM (SELECT * FROM y) AS z /* source: x */' 4762 4763 Args: 4764 expression: The expression to expand. 4765 sources: A dictionary of name to Subqueryables. 4766 copy: Whether or not to copy the expression during transformation. Defaults to True. 4767 4768 Returns: 4769 The transformed expression. 4770 """ 4771 4772 def _expand(node: Expression): 4773 if isinstance(node, Table): 4774 name = table_name(node) 4775 source = sources.get(name) 4776 if source: 4777 subquery = source.subquery(node.alias or name) 4778 subquery.comments = [f"source: {name}"] 4779 return subquery 4780 return node 4781 4782 return expression.transform(_expand, copy=copy) 4783 4784 4785def func(name: str, *args, dialect: DialectType = None, **kwargs) -> Func: 4786 """ 4787 Returns a Func expression. 4788 4789 Examples: 4790 >>> func("abs", 5).sql() 4791 'ABS(5)' 4792 4793 >>> func("cast", this=5, to=DataType.build("DOUBLE")).sql() 4794 'CAST(5 AS DOUBLE)' 4795 4796 Args: 4797 name: the name of the function to build. 4798 args: the args used to instantiate the function of interest. 4799 dialect: the source dialect. 4800 kwargs: the kwargs used to instantiate the function of interest. 4801 4802 Note: 4803 The arguments `args` and `kwargs` are mutually exclusive. 4804 4805 Returns: 4806 An instance of the function of interest, or an anonymous function, if `name` doesn't 4807 correspond to an existing `sqlglot.expressions.Func` class. 4808 """ 4809 if args and kwargs: 4810 raise ValueError("Can't use both args and kwargs to instantiate a function.") 4811 4812 from sqlglot.dialects.dialect import Dialect 4813 4814 args = tuple(convert(arg) for arg in args) 4815 kwargs = {key: convert(value) for key, value in kwargs.items()} 4816 4817 parser = Dialect.get_or_raise(dialect)().parser() 4818 from_args_list = parser.FUNCTIONS.get(name.upper()) 4819 4820 if from_args_list: 4821 function = from_args_list(args) if args else from_args_list.__self__(**kwargs) # type: ignore 4822 else: 4823 kwargs = kwargs or {"expressions": args} 4824 function = Anonymous(this=name, **kwargs) 4825 4826 for error_message in function.error_messages(args): 4827 raise ValueError(error_message) 4828 4829 return function 4830 4831 4832def true(): 4833 """ 4834 Returns a true Boolean expression. 4835 """ 4836 return Boolean(this=True) 4837 4838 4839def false(): 4840 """ 4841 Returns a false Boolean expression. 4842 """ 4843 return Boolean(this=False) 4844 4845 4846def null(): 4847 """ 4848 Returns a Null expression. 4849 """ 4850 return Null() 4851 4852 4853# TODO: deprecate this 4854TRUE = Boolean(this=True) 4855FALSE = Boolean(this=False) 4856NULL = Null()
class
Expression:
54class Expression(metaclass=_Expression): 55 """ 56 The base class for all expressions in a syntax tree. Each Expression encapsulates any necessary 57 context, such as its child expressions, their names (arg keys), and whether a given child expression 58 is optional or not. 59 60 Attributes: 61 key: a unique key for each class in the Expression hierarchy. This is useful for hashing 62 and representing expressions as strings. 63 arg_types: determines what arguments (child nodes) are supported by an expression. It 64 maps arg keys to booleans that indicate whether the corresponding args are optional. 65 66 Example: 67 >>> class Foo(Expression): 68 ... arg_types = {"this": True, "expression": False} 69 70 The above definition informs us that Foo is an Expression that requires an argument called 71 "this" and may also optionally receive an argument called "expression". 72 73 Args: 74 args: a mapping used for retrieving the arguments of an expression, given their arg keys. 75 parent: a reference to the parent expression (or None, in case of root expressions). 76 arg_key: the arg key an expression is associated with, i.e. the name its parent expression 77 uses to refer to it. 78 comments: a list of comments that are associated with a given expression. This is used in 79 order to preserve comments when transpiling SQL code. 80 _type: the `sqlglot.expressions.DataType` type of an expression. This is inferred by the 81 optimizer, in order to enable some transformations that require type information. 82 """ 83 84 key = "expression" 85 arg_types = {"this": True} 86 __slots__ = ("args", "parent", "arg_key", "comments", "_type", "_meta") 87 88 def __init__(self, **args: t.Any): 89 self.args: t.Dict[str, t.Any] = args 90 self.parent: t.Optional[Expression] = None 91 self.arg_key: t.Optional[str] = None 92 self.comments: t.Optional[t.List[str]] = None 93 self._type: t.Optional[DataType] = None 94 self._meta: t.Optional[t.Dict[str, t.Any]] = None 95 96 for arg_key, value in self.args.items(): 97 self._set_parent(arg_key, value) 98 99 def __eq__(self, other) -> bool: 100 return type(self) is type(other) and _norm_args(self) == _norm_args(other) 101 102 def __hash__(self) -> int: 103 return hash( 104 ( 105 self.key, 106 tuple( 107 (k, tuple(v) if isinstance(v, list) else v) for k, v in _norm_args(self).items() 108 ), 109 ) 110 ) 111 112 @property 113 def this(self): 114 """ 115 Retrieves the argument with key "this". 116 """ 117 return self.args.get("this") 118 119 @property 120 def expression(self): 121 """ 122 Retrieves the argument with key "expression". 123 """ 124 return self.args.get("expression") 125 126 @property 127 def expressions(self): 128 """ 129 Retrieves the argument with key "expressions". 130 """ 131 return self.args.get("expressions") or [] 132 133 def text(self, key) -> str: 134 """ 135 Returns a textual representation of the argument corresponding to "key". This can only be used 136 for args that are strings or leaf Expression instances, such as identifiers and literals. 137 """ 138 field = self.args.get(key) 139 if isinstance(field, str): 140 return field 141 if isinstance(field, (Identifier, Literal, Var)): 142 return field.this 143 if isinstance(field, (Star, Null)): 144 return field.name 145 return "" 146 147 @property 148 def is_string(self) -> bool: 149 """ 150 Checks whether a Literal expression is a string. 151 """ 152 return isinstance(self, Literal) and self.args["is_string"] 153 154 @property 155 def is_number(self) -> bool: 156 """ 157 Checks whether a Literal expression is a number. 158 """ 159 return isinstance(self, Literal) and not self.args["is_string"] 160 161 @property 162 def is_int(self) -> bool: 163 """ 164 Checks whether a Literal expression is an integer. 165 """ 166 if self.is_number: 167 try: 168 int(self.name) 169 return True 170 except ValueError: 171 pass 172 return False 173 174 @property 175 def is_star(self) -> bool: 176 """Checks whether an expression is a star.""" 177 return isinstance(self, Star) or (isinstance(self, Column) and isinstance(self.this, Star)) 178 179 @property 180 def alias(self) -> str: 181 """ 182 Returns the alias of the expression, or an empty string if it's not aliased. 183 """ 184 if isinstance(self.args.get("alias"), TableAlias): 185 return self.args["alias"].name 186 return self.text("alias") 187 188 @property 189 def name(self) -> str: 190 return self.text("this") 191 192 @property 193 def alias_or_name(self): 194 return self.alias or self.name 195 196 @property 197 def output_name(self): 198 """ 199 Name of the output column if this expression is a selection. 200 201 If the Expression has no output name, an empty string is returned. 202 203 Example: 204 >>> from sqlglot import parse_one 205 >>> parse_one("SELECT a").expressions[0].output_name 206 'a' 207 >>> parse_one("SELECT b AS c").expressions[0].output_name 208 'c' 209 >>> parse_one("SELECT 1 + 2").expressions[0].output_name 210 '' 211 """ 212 return "" 213 214 @property 215 def type(self) -> t.Optional[DataType]: 216 return self._type 217 218 @type.setter 219 def type(self, dtype: t.Optional[DataType | DataType.Type | str]) -> None: 220 if dtype and not isinstance(dtype, DataType): 221 dtype = DataType.build(dtype) 222 self._type = dtype # type: ignore 223 224 @property 225 def meta(self) -> t.Dict[str, t.Any]: 226 if self._meta is None: 227 self._meta = {} 228 return self._meta 229 230 def __deepcopy__(self, memo): 231 copy = self.__class__(**deepcopy(self.args)) 232 if self.comments is not None: 233 copy.comments = deepcopy(self.comments) 234 235 if self._type is not None: 236 copy._type = self._type.copy() 237 238 if self._meta is not None: 239 copy._meta = deepcopy(self._meta) 240 241 return copy 242 243 def copy(self): 244 """ 245 Returns a deep copy of the expression. 246 """ 247 new = deepcopy(self) 248 new.parent = self.parent 249 for item, parent, _ in new.bfs(): 250 if isinstance(item, Expression) and parent: 251 item.parent = parent 252 return new 253 254 def append(self, arg_key, value): 255 """ 256 Appends value to arg_key if it's a list or sets it as a new list. 257 258 Args: 259 arg_key (str): name of the list expression arg 260 value (Any): value to append to the list 261 """ 262 if not isinstance(self.args.get(arg_key), list): 263 self.args[arg_key] = [] 264 self.args[arg_key].append(value) 265 self._set_parent(arg_key, value) 266 267 def set(self, arg_key, value): 268 """ 269 Sets `arg_key` to `value`. 270 271 Args: 272 arg_key (str): name of the expression arg. 273 value: value to set the arg to. 274 """ 275 self.args[arg_key] = value 276 self._set_parent(arg_key, value) 277 278 def _set_parent(self, arg_key, value): 279 if isinstance(value, Expression): 280 value.parent = self 281 value.arg_key = arg_key 282 elif isinstance(value, list): 283 for v in value: 284 if isinstance(v, Expression): 285 v.parent = self 286 v.arg_key = arg_key 287 288 @property 289 def depth(self): 290 """ 291 Returns the depth of this tree. 292 """ 293 if self.parent: 294 return self.parent.depth + 1 295 return 0 296 297 def find(self, *expression_types, bfs=True): 298 """ 299 Returns the first node in this tree which matches at least one of 300 the specified types. 301 302 Args: 303 expression_types (type): the expression type(s) to match. 304 305 Returns: 306 The node which matches the criteria or None if no such node was found. 307 """ 308 return next(self.find_all(*expression_types, bfs=bfs), None) 309 310 def find_all(self, *expression_types, bfs=True): 311 """ 312 Returns a generator object which visits all nodes in this tree and only 313 yields those that match at least one of the specified expression types. 314 315 Args: 316 expression_types (type): the expression type(s) to match. 317 318 Returns: 319 The generator object. 320 """ 321 for expression, _, _ in self.walk(bfs=bfs): 322 if isinstance(expression, expression_types): 323 yield expression 324 325 def find_ancestor(self, *expression_types): 326 """ 327 Returns a nearest parent matching expression_types. 328 329 Args: 330 expression_types (type): the expression type(s) to match. 331 332 Returns: 333 The parent node. 334 """ 335 ancestor = self.parent 336 while ancestor and not isinstance(ancestor, expression_types): 337 ancestor = ancestor.parent 338 return ancestor 339 340 @property 341 def parent_select(self): 342 """ 343 Returns the parent select statement. 344 """ 345 return self.find_ancestor(Select) 346 347 def root(self) -> Expression: 348 """ 349 Returns the root expression of this tree. 350 """ 351 expression = self 352 while expression.parent: 353 expression = expression.parent 354 return expression 355 356 def walk(self, bfs=True, prune=None): 357 """ 358 Returns a generator object which visits all nodes in this tree. 359 360 Args: 361 bfs (bool): if set to True the BFS traversal order will be applied, 362 otherwise the DFS traversal will be used instead. 363 prune ((node, parent, arg_key) -> bool): callable that returns True if 364 the generator should stop traversing this branch of the tree. 365 366 Returns: 367 the generator object. 368 """ 369 if bfs: 370 yield from self.bfs(prune=prune) 371 else: 372 yield from self.dfs(prune=prune) 373 374 def dfs(self, parent=None, key=None, prune=None): 375 """ 376 Returns a generator object which visits all nodes in this tree in 377 the DFS (Depth-first) order. 378 379 Returns: 380 The generator object. 381 """ 382 parent = parent or self.parent 383 yield self, parent, key 384 if prune and prune(self, parent, key): 385 return 386 387 for k, v in self.args.items(): 388 for node in ensure_collection(v): 389 if isinstance(node, Expression): 390 yield from node.dfs(self, k, prune) 391 392 def bfs(self, prune=None): 393 """ 394 Returns a generator object which visits all nodes in this tree in 395 the BFS (Breadth-first) order. 396 397 Returns: 398 The generator object. 399 """ 400 queue = deque([(self, self.parent, None)]) 401 402 while queue: 403 item, parent, key = queue.popleft() 404 405 yield item, parent, key 406 if prune and prune(item, parent, key): 407 continue 408 409 if isinstance(item, Expression): 410 for k, v in item.args.items(): 411 for node in ensure_collection(v): 412 if isinstance(node, Expression): 413 queue.append((node, item, k)) 414 415 def unnest(self): 416 """ 417 Returns the first non parenthesis child or self. 418 """ 419 expression = self 420 while isinstance(expression, Paren): 421 expression = expression.this 422 return expression 423 424 def unalias(self): 425 """ 426 Returns the inner expression if this is an Alias. 427 """ 428 if isinstance(self, Alias): 429 return self.this 430 return self 431 432 def unnest_operands(self): 433 """ 434 Returns unnested operands as a tuple. 435 """ 436 return tuple(arg.unnest() for arg in self.args.values() if arg) 437 438 def flatten(self, unnest=True): 439 """ 440 Returns a generator which yields child nodes who's parents are the same class. 441 442 A AND B AND C -> [A, B, C] 443 """ 444 for node, _, _ in self.dfs(prune=lambda n, p, *_: p and not isinstance(n, self.__class__)): 445 if not isinstance(node, self.__class__): 446 yield node.unnest() if unnest else node 447 448 def __str__(self): 449 return self.sql() 450 451 def __repr__(self): 452 return self._to_s() 453 454 def sql(self, dialect: DialectType = None, **opts) -> str: 455 """ 456 Returns SQL string representation of this tree. 457 458 Args: 459 dialect: the dialect of the output SQL string (eg. "spark", "hive", "presto", "mysql"). 460 opts: other `sqlglot.generator.Generator` options. 461 462 Returns: 463 The SQL string. 464 """ 465 from sqlglot.dialects import Dialect 466 467 return Dialect.get_or_raise(dialect)().generate(self, **opts) 468 469 def _to_s(self, hide_missing: bool = True, level: int = 0) -> str: 470 indent = "" if not level else "\n" 471 indent += "".join([" "] * level) 472 left = f"({self.key.upper()} " 473 474 args: t.Dict[str, t.Any] = { 475 k: ", ".join( 476 v._to_s(hide_missing=hide_missing, level=level + 1) 477 if hasattr(v, "_to_s") 478 else str(v) 479 for v in ensure_collection(vs) 480 if v is not None 481 ) 482 for k, vs in self.args.items() 483 } 484 args["comments"] = self.comments 485 args["type"] = self.type 486 args = {k: v for k, v in args.items() if v or not hide_missing} 487 488 right = ", ".join(f"{k}: {v}" for k, v in args.items()) 489 right += ")" 490 491 return indent + left + right 492 493 def transform(self, fun, *args, copy=True, **kwargs): 494 """ 495 Recursively visits all tree nodes (excluding already transformed ones) 496 and applies the given transformation function to each node. 497 498 Args: 499 fun (function): a function which takes a node as an argument and returns a 500 new transformed node or the same node without modifications. If the function 501 returns None, then the corresponding node will be removed from the syntax tree. 502 copy (bool): if set to True a new tree instance is constructed, otherwise the tree is 503 modified in place. 504 505 Returns: 506 The transformed tree. 507 """ 508 node = self.copy() if copy else self 509 new_node = fun(node, *args, **kwargs) 510 511 if new_node is None or not isinstance(new_node, Expression): 512 return new_node 513 if new_node is not node: 514 new_node.parent = node.parent 515 return new_node 516 517 replace_children(new_node, lambda child: child.transform(fun, *args, copy=False, **kwargs)) 518 return new_node 519 520 def replace(self, expression): 521 """ 522 Swap out this expression with a new expression. 523 524 For example:: 525 526 >>> tree = Select().select("x").from_("tbl") 527 >>> tree.find(Column).replace(Column(this="y")) 528 (COLUMN this: y) 529 >>> tree.sql() 530 'SELECT y FROM tbl' 531 532 Args: 533 expression (Expression|None): new node 534 535 Returns: 536 The new expression or expressions. 537 """ 538 if not self.parent: 539 return expression 540 541 parent = self.parent 542 self.parent = None 543 544 replace_children(parent, lambda child: expression if child is self else child) 545 return expression 546 547 def pop(self): 548 """ 549 Remove this expression from its AST. 550 """ 551 self.replace(None) 552 553 def assert_is(self, type_): 554 """ 555 Assert that this `Expression` is an instance of `type_`. 556 557 If it is NOT an instance of `type_`, this raises an assertion error. 558 Otherwise, this returns this expression. 559 560 Examples: 561 This is useful for type security in chained expressions: 562 563 >>> import sqlglot 564 >>> sqlglot.parse_one("SELECT x from y").assert_is(Select).select("z").sql() 565 'SELECT x, z FROM y' 566 """ 567 assert isinstance(self, type_) 568 return self 569 570 def error_messages(self, args: t.Optional[t.Sequence] = None) -> t.List[str]: 571 """ 572 Checks if this expression is valid (e.g. all mandatory args are set). 573 574 Args: 575 args: a sequence of values that were used to instantiate a Func expression. This is used 576 to check that the provided arguments don't exceed the function argument limit. 577 578 Returns: 579 A list of error messages for all possible errors that were found. 580 """ 581 errors: t.List[str] = [] 582 583 for k in self.args: 584 if k not in self.arg_types: 585 errors.append(f"Unexpected keyword: '{k}' for {self.__class__}") 586 for k, mandatory in self.arg_types.items(): 587 v = self.args.get(k) 588 if mandatory and (v is None or (isinstance(v, list) and not v)): 589 errors.append(f"Required keyword: '{k}' missing for {self.__class__}") 590 591 if ( 592 args 593 and isinstance(self, Func) 594 and len(args) > len(self.arg_types) 595 and not self.is_var_len_args 596 ): 597 errors.append( 598 f"The number of provided arguments ({len(args)}) is greater than " 599 f"the maximum number of supported arguments ({len(self.arg_types)})" 600 ) 601 602 return errors 603 604 def dump(self): 605 """ 606 Dump this Expression to a JSON-serializable dict. 607 """ 608 from sqlglot.serde import dump 609 610 return dump(self) 611 612 @classmethod 613 def load(cls, obj): 614 """ 615 Load a dict (as returned by `Expression.dump`) into an Expression instance. 616 """ 617 from sqlglot.serde import load 618 619 return load(obj)
The base class for all expressions in a syntax tree. Each Expression encapsulates any necessary context, such as its child expressions, their names (arg keys), and whether a given child expression is optional or not.
Attributes:
- key: a unique key for each class in the Expression hierarchy. This is useful for hashing and representing expressions as strings.
- arg_types: determines what arguments (child nodes) are supported by an expression. It maps arg keys to booleans that indicate whether the corresponding args are optional.
Example:
>>> class Foo(Expression): ... arg_types = {"this": True, "expression": False}The above definition informs us that Foo is an Expression that requires an argument called "this" and may also optionally receive an argument called "expression".
Arguments:
- args: a mapping used for retrieving the arguments of an expression, given their arg keys.
- parent: a reference to the parent expression (or None, in case of root expressions).
- arg_key: the arg key an expression is associated with, i.e. the name its parent expression uses to refer to it.
- comments: a list of comments that are associated with a given expression. This is used in order to preserve comments when transpiling SQL code.
- _type: the
sqlglot.expressions.DataTypetype of an expression. This is inferred by the optimizer, in order to enable some transformations that require type information.
Expression(**args: Any)
88 def __init__(self, **args: t.Any): 89 self.args: t.Dict[str, t.Any] = args 90 self.parent: t.Optional[Expression] = None 91 self.arg_key: t.Optional[str] = None 92 self.comments: t.Optional[t.List[str]] = None 93 self._type: t.Optional[DataType] = None 94 self._meta: t.Optional[t.Dict[str, t.Any]] = None 95 96 for arg_key, value in self.args.items(): 97 self._set_parent(arg_key, value)
def
text(self, key) -> str:
133 def text(self, key) -> str: 134 """ 135 Returns a textual representation of the argument corresponding to "key". This can only be used 136 for args that are strings or leaf Expression instances, such as identifiers and literals. 137 """ 138 field = self.args.get(key) 139 if isinstance(field, str): 140 return field 141 if isinstance(field, (Identifier, Literal, Var)): 142 return field.this 143 if isinstance(field, (Star, Null)): 144 return field.name 145 return ""
Returns a textual representation of the argument corresponding to "key". This can only be used for args that are strings or leaf Expression instances, such as identifiers and literals.
output_name
Name of the output column if this expression is a selection.
If the Expression has no output name, an empty string is returned.
Example:
>>> from sqlglot import parse_one >>> parse_one("SELECT a").expressions[0].output_name 'a' >>> parse_one("SELECT b AS c").expressions[0].output_name 'c' >>> parse_one("SELECT 1 + 2").expressions[0].output_name ''
def
copy(self):
243 def copy(self): 244 """ 245 Returns a deep copy of the expression. 246 """ 247 new = deepcopy(self) 248 new.parent = self.parent 249 for item, parent, _ in new.bfs(): 250 if isinstance(item, Expression) and parent: 251 item.parent = parent 252 return new
Returns a deep copy of the expression.
def
append(self, arg_key, value):
254 def append(self, arg_key, value): 255 """ 256 Appends value to arg_key if it's a list or sets it as a new list. 257 258 Args: 259 arg_key (str): name of the list expression arg 260 value (Any): value to append to the list 261 """ 262 if not isinstance(self.args.get(arg_key), list): 263 self.args[arg_key] = [] 264 self.args[arg_key].append(value) 265 self._set_parent(arg_key, value)
Appends value to arg_key if it's a list or sets it as a new list.
Arguments:
- arg_key (str): name of the list expression arg
- value (Any): value to append to the list
def
set(self, arg_key, value):
267 def set(self, arg_key, value): 268 """ 269 Sets `arg_key` to `value`. 270 271 Args: 272 arg_key (str): name of the expression arg. 273 value: value to set the arg to. 274 """ 275 self.args[arg_key] = value 276 self._set_parent(arg_key, value)
Sets arg_key to value.
Arguments:
- arg_key (str): name of the expression arg.
- value: value to set the arg to.
def
find(self, *expression_types, bfs=True):
297 def find(self, *expression_types, bfs=True): 298 """ 299 Returns the first node in this tree which matches at least one of 300 the specified types. 301 302 Args: 303 expression_types (type): the expression type(s) to match. 304 305 Returns: 306 The node which matches the criteria or None if no such node was found. 307 """ 308 return next(self.find_all(*expression_types, bfs=bfs), None)
Returns the first node in this tree which matches at least one of the specified types.
Arguments:
- expression_types (type): the expression type(s) to match.
Returns:
The node which matches the criteria or None if no such node was found.
def
find_all(self, *expression_types, bfs=True):
310 def find_all(self, *expression_types, bfs=True): 311 """ 312 Returns a generator object which visits all nodes in this tree and only 313 yields those that match at least one of the specified expression types. 314 315 Args: 316 expression_types (type): the expression type(s) to match. 317 318 Returns: 319 The generator object. 320 """ 321 for expression, _, _ in self.walk(bfs=bfs): 322 if isinstance(expression, expression_types): 323 yield expression
Returns a generator object which visits all nodes in this tree and only yields those that match at least one of the specified expression types.
Arguments:
- expression_types (type): the expression type(s) to match.
Returns:
The generator object.
def
find_ancestor(self, *expression_types):
325 def find_ancestor(self, *expression_types): 326 """ 327 Returns a nearest parent matching expression_types. 328 329 Args: 330 expression_types (type): the expression type(s) to match. 331 332 Returns: 333 The parent node. 334 """ 335 ancestor = self.parent 336 while ancestor and not isinstance(ancestor, expression_types): 337 ancestor = ancestor.parent 338 return ancestor
Returns a nearest parent matching expression_types.
Arguments:
- expression_types (type): the expression type(s) to match.
Returns:
The parent node.
347 def root(self) -> Expression: 348 """ 349 Returns the root expression of this tree. 350 """ 351 expression = self 352 while expression.parent: 353 expression = expression.parent 354 return expression
Returns the root expression of this tree.
def
walk(self, bfs=True, prune=None):
356 def walk(self, bfs=True, prune=None): 357 """ 358 Returns a generator object which visits all nodes in this tree. 359 360 Args: 361 bfs (bool): if set to True the BFS traversal order will be applied, 362 otherwise the DFS traversal will be used instead. 363 prune ((node, parent, arg_key) -> bool): callable that returns True if 364 the generator should stop traversing this branch of the tree. 365 366 Returns: 367 the generator object. 368 """ 369 if bfs: 370 yield from self.bfs(prune=prune) 371 else: 372 yield from self.dfs(prune=prune)
Returns a generator object which visits all nodes in this tree.
Arguments:
- bfs (bool): if set to True the BFS traversal order will be applied, otherwise the DFS traversal will be used instead.
- prune ((node, parent, arg_key) -> bool): callable that returns True if the generator should stop traversing this branch of the tree.
Returns:
the generator object.
def
dfs(self, parent=None, key=None, prune=None):
374 def dfs(self, parent=None, key=None, prune=None): 375 """ 376 Returns a generator object which visits all nodes in this tree in 377 the DFS (Depth-first) order. 378 379 Returns: 380 The generator object. 381 """ 382 parent = parent or self.parent 383 yield self, parent, key 384 if prune and prune(self, parent, key): 385 return 386 387 for k, v in self.args.items(): 388 for node in ensure_collection(v): 389 if isinstance(node, Expression): 390 yield from node.dfs(self, k, prune)
Returns a generator object which visits all nodes in this tree in the DFS (Depth-first) order.
Returns:
The generator object.
def
bfs(self, prune=None):
392 def bfs(self, prune=None): 393 """ 394 Returns a generator object which visits all nodes in this tree in 395 the BFS (Breadth-first) order. 396 397 Returns: 398 The generator object. 399 """ 400 queue = deque([(self, self.parent, None)]) 401 402 while queue: 403 item, parent, key = queue.popleft() 404 405 yield item, parent, key 406 if prune and prune(item, parent, key): 407 continue 408 409 if isinstance(item, Expression): 410 for k, v in item.args.items(): 411 for node in ensure_collection(v): 412 if isinstance(node, Expression): 413 queue.append((node, item, k))
Returns a generator object which visits all nodes in this tree in the BFS (Breadth-first) order.
Returns:
The generator object.
def
unnest(self):
415 def unnest(self): 416 """ 417 Returns the first non parenthesis child or self. 418 """ 419 expression = self 420 while isinstance(expression, Paren): 421 expression = expression.this 422 return expression
Returns the first non parenthesis child or self.
def
unalias(self):
424 def unalias(self): 425 """ 426 Returns the inner expression if this is an Alias. 427 """ 428 if isinstance(self, Alias): 429 return self.this 430 return self
Returns the inner expression if this is an Alias.
def
unnest_operands(self):
432 def unnest_operands(self): 433 """ 434 Returns unnested operands as a tuple. 435 """ 436 return tuple(arg.unnest() for arg in self.args.values() if arg)
Returns unnested operands as a tuple.
def
flatten(self, unnest=True):
438 def flatten(self, unnest=True): 439 """ 440 Returns a generator which yields child nodes who's parents are the same class. 441 442 A AND B AND C -> [A, B, C] 443 """ 444 for node, _, _ in self.dfs(prune=lambda n, p, *_: p and not isinstance(n, self.__class__)): 445 if not isinstance(node, self.__class__): 446 yield node.unnest() if unnest else node
Returns a generator which yields child nodes who's parents are the same class.
A AND B AND C -> [A, B, C]
def
sql( self, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, **opts) -> str:
454 def sql(self, dialect: DialectType = None, **opts) -> str: 455 """ 456 Returns SQL string representation of this tree. 457 458 Args: 459 dialect: the dialect of the output SQL string (eg. "spark", "hive", "presto", "mysql"). 460 opts: other `sqlglot.generator.Generator` options. 461 462 Returns: 463 The SQL string. 464 """ 465 from sqlglot.dialects import Dialect 466 467 return Dialect.get_or_raise(dialect)().generate(self, **opts)
Returns SQL string representation of this tree.
Arguments:
- dialect: the dialect of the output SQL string (eg. "spark", "hive", "presto", "mysql").
- opts: other
sqlglot.generator.Generatoroptions.
Returns:
The SQL string.
def
transform(self, fun, *args, copy=True, **kwargs):
493 def transform(self, fun, *args, copy=True, **kwargs): 494 """ 495 Recursively visits all tree nodes (excluding already transformed ones) 496 and applies the given transformation function to each node. 497 498 Args: 499 fun (function): a function which takes a node as an argument and returns a 500 new transformed node or the same node without modifications. If the function 501 returns None, then the corresponding node will be removed from the syntax tree. 502 copy (bool): if set to True a new tree instance is constructed, otherwise the tree is 503 modified in place. 504 505 Returns: 506 The transformed tree. 507 """ 508 node = self.copy() if copy else self 509 new_node = fun(node, *args, **kwargs) 510 511 if new_node is None or not isinstance(new_node, Expression): 512 return new_node 513 if new_node is not node: 514 new_node.parent = node.parent 515 return new_node 516 517 replace_children(new_node, lambda child: child.transform(fun, *args, copy=False, **kwargs)) 518 return new_node
Recursively visits all tree nodes (excluding already transformed ones) and applies the given transformation function to each node.
Arguments:
- fun (function): a function which takes a node as an argument and returns a new transformed node or the same node without modifications. If the function returns None, then the corresponding node will be removed from the syntax tree.
- copy (bool): if set to True a new tree instance is constructed, otherwise the tree is modified in place.
Returns:
The transformed tree.
def
replace(self, expression):
520 def replace(self, expression): 521 """ 522 Swap out this expression with a new expression. 523 524 For example:: 525 526 >>> tree = Select().select("x").from_("tbl") 527 >>> tree.find(Column).replace(Column(this="y")) 528 (COLUMN this: y) 529 >>> tree.sql() 530 'SELECT y FROM tbl' 531 532 Args: 533 expression (Expression|None): new node 534 535 Returns: 536 The new expression or expressions. 537 """ 538 if not self.parent: 539 return expression 540 541 parent = self.parent 542 self.parent = None 543 544 replace_children(parent, lambda child: expression if child is self else child) 545 return expression
Swap out this expression with a new expression.
For example::
>>> tree = Select().select("x").from_("tbl")
>>> tree.find(Column).replace(Column(this="y"))
(COLUMN this: y)
>>> tree.sql()
'SELECT y FROM tbl'
Arguments:
- expression (Expression|None): new node
Returns:
The new expression or expressions.
def
assert_is(self, type_):
553 def assert_is(self, type_): 554 """ 555 Assert that this `Expression` is an instance of `type_`. 556 557 If it is NOT an instance of `type_`, this raises an assertion error. 558 Otherwise, this returns this expression. 559 560 Examples: 561 This is useful for type security in chained expressions: 562 563 >>> import sqlglot 564 >>> sqlglot.parse_one("SELECT x from y").assert_is(Select).select("z").sql() 565 'SELECT x, z FROM y' 566 """ 567 assert isinstance(self, type_) 568 return self
Assert that this Expression is an instance of type_.
If it is NOT an instance of type_, this raises an assertion error.
Otherwise, this returns this expression.
Examples:
This is useful for type security in chained expressions:
>>> import sqlglot >>> sqlglot.parse_one("SELECT x from y").assert_is(Select).select("z").sql() 'SELECT x, z FROM y'
def
error_messages(self, args: Optional[Sequence] = None) -> List[str]:
570 def error_messages(self, args: t.Optional[t.Sequence] = None) -> t.List[str]: 571 """ 572 Checks if this expression is valid (e.g. all mandatory args are set). 573 574 Args: 575 args: a sequence of values that were used to instantiate a Func expression. This is used 576 to check that the provided arguments don't exceed the function argument limit. 577 578 Returns: 579 A list of error messages for all possible errors that were found. 580 """ 581 errors: t.List[str] = [] 582 583 for k in self.args: 584 if k not in self.arg_types: 585 errors.append(f"Unexpected keyword: '{k}' for {self.__class__}") 586 for k, mandatory in self.arg_types.items(): 587 v = self.args.get(k) 588 if mandatory and (v is None or (isinstance(v, list) and not v)): 589 errors.append(f"Required keyword: '{k}' missing for {self.__class__}") 590 591 if ( 592 args 593 and isinstance(self, Func) 594 and len(args) > len(self.arg_types) 595 and not self.is_var_len_args 596 ): 597 errors.append( 598 f"The number of provided arguments ({len(args)}) is greater than " 599 f"the maximum number of supported arguments ({len(self.arg_types)})" 600 ) 601 602 return errors
Checks if this expression is valid (e.g. all mandatory args are set).
Arguments:
- args: a sequence of values that were used to instantiate a Func expression. This is used to check that the provided arguments don't exceed the function argument limit.
Returns:
A list of error messages for all possible errors that were found.
def
dump(self):
604 def dump(self): 605 """ 606 Dump this Expression to a JSON-serializable dict. 607 """ 608 from sqlglot.serde import dump 609 610 return dump(self)
Dump this Expression to a JSON-serializable dict.
@classmethod
def
load(cls, obj):
612 @classmethod 613 def load(cls, obj): 614 """ 615 Load a dict (as returned by `Expression.dump`) into an Expression instance. 616 """ 617 from sqlglot.serde import load 618 619 return load(obj)
Load a dict (as returned by Expression.dump) into an Expression instance.
629class Condition(Expression): 630 def and_(self, *expressions, dialect=None, **opts): 631 """ 632 AND this condition with one or multiple expressions. 633 634 Example: 635 >>> condition("x=1").and_("y=1").sql() 636 'x = 1 AND y = 1' 637 638 Args: 639 *expressions (str | Expression): the SQL code strings to parse. 640 If an `Expression` instance is passed, it will be used as-is. 641 dialect (str): the dialect used to parse the input expression. 642 opts (kwargs): other options to use to parse the input expressions. 643 644 Returns: 645 And: the new condition. 646 """ 647 return and_(self, *expressions, dialect=dialect, **opts) 648 649 def or_(self, *expressions, dialect=None, **opts): 650 """ 651 OR this condition with one or multiple expressions. 652 653 Example: 654 >>> condition("x=1").or_("y=1").sql() 655 'x = 1 OR y = 1' 656 657 Args: 658 *expressions (str | Expression): the SQL code strings to parse. 659 If an `Expression` instance is passed, it will be used as-is. 660 dialect (str): the dialect used to parse the input expression. 661 opts (kwargs): other options to use to parse the input expressions. 662 663 Returns: 664 Or: the new condition. 665 """ 666 return or_(self, *expressions, dialect=dialect, **opts) 667 668 def not_(self): 669 """ 670 Wrap this condition with NOT. 671 672 Example: 673 >>> condition("x=1").not_().sql() 674 'NOT x = 1' 675 676 Returns: 677 Not: the new condition. 678 """ 679 return not_(self)
def
and_(self, *expressions, dialect=None, **opts):
630 def and_(self, *expressions, dialect=None, **opts): 631 """ 632 AND this condition with one or multiple expressions. 633 634 Example: 635 >>> condition("x=1").and_("y=1").sql() 636 'x = 1 AND y = 1' 637 638 Args: 639 *expressions (str | Expression): the SQL code strings to parse. 640 If an `Expression` instance is passed, it will be used as-is. 641 dialect (str): the dialect used to parse the input expression. 642 opts (kwargs): other options to use to parse the input expressions. 643 644 Returns: 645 And: the new condition. 646 """ 647 return and_(self, *expressions, dialect=dialect, **opts)
AND this condition with one or multiple expressions.
Example:
>>> condition("x=1").and_("y=1").sql() 'x = 1 AND y = 1'
Arguments:
- *expressions (str | Expression): the SQL code strings to parse.
If an
Expressioninstance is passed, it will be used as-is. - dialect (str): the dialect used to parse the input expression.
- opts (kwargs): other options to use to parse the input expressions.
Returns:
And: the new condition.
def
or_(self, *expressions, dialect=None, **opts):
649 def or_(self, *expressions, dialect=None, **opts): 650 """ 651 OR this condition with one or multiple expressions. 652 653 Example: 654 >>> condition("x=1").or_("y=1").sql() 655 'x = 1 OR y = 1' 656 657 Args: 658 *expressions (str | Expression): the SQL code strings to parse. 659 If an `Expression` instance is passed, it will be used as-is. 660 dialect (str): the dialect used to parse the input expression. 661 opts (kwargs): other options to use to parse the input expressions. 662 663 Returns: 664 Or: the new condition. 665 """ 666 return or_(self, *expressions, dialect=dialect, **opts)
OR this condition with one or multiple expressions.
Example:
>>> condition("x=1").or_("y=1").sql() 'x = 1 OR y = 1'
Arguments:
- *expressions (str | Expression): the SQL code strings to parse.
If an
Expressioninstance is passed, it will be used as-is. - dialect (str): the dialect used to parse the input expression.
- opts (kwargs): other options to use to parse the input expressions.
Returns:
Or: the new condition.
def
not_(self):
668 def not_(self): 669 """ 670 Wrap this condition with NOT. 671 672 Example: 673 >>> condition("x=1").not_().sql() 674 'NOT x = 1' 675 676 Returns: 677 Not: the new condition. 678 """ 679 return not_(self)
Wrap this condition with NOT.
Example:
>>> condition("x=1").not_().sql() 'NOT x = 1'
Returns:
Not: the new condition.
Inherited Members
Relationships like x = y, x > 1, x >= y.
Inherited Members
686class DerivedTable(Expression): 687 @property 688 def alias_column_names(self): 689 table_alias = self.args.get("alias") 690 if not table_alias: 691 return [] 692 column_list = table_alias.assert_is(TableAlias).args.get("columns") or [] 693 return [c.name for c in column_list] 694 695 @property 696 def selects(self): 697 alias = self.args.get("alias") 698 699 if alias: 700 return alias.columns 701 return [] 702 703 @property 704 def named_selects(self): 705 return [select.output_name for select in self.selects]
Inherited Members
708class Unionable(Expression): 709 def union(self, expression, distinct=True, dialect=None, **opts): 710 """ 711 Builds a UNION expression. 712 713 Example: 714 >>> import sqlglot 715 >>> sqlglot.parse_one("SELECT * FROM foo").union("SELECT * FROM bla").sql() 716 'SELECT * FROM foo UNION SELECT * FROM bla' 717 718 Args: 719 expression (str | Expression): the SQL code string. 720 If an `Expression` instance is passed, it will be used as-is. 721 distinct (bool): set the DISTINCT flag if and only if this is true. 722 dialect (str): the dialect used to parse the input expression. 723 opts (kwargs): other options to use to parse the input expressions. 724 Returns: 725 Union: the Union expression. 726 """ 727 return union(left=self, right=expression, distinct=distinct, dialect=dialect, **opts) 728 729 def intersect(self, expression, distinct=True, dialect=None, **opts): 730 """ 731 Builds an INTERSECT expression. 732 733 Example: 734 >>> import sqlglot 735 >>> sqlglot.parse_one("SELECT * FROM foo").intersect("SELECT * FROM bla").sql() 736 'SELECT * FROM foo INTERSECT SELECT * FROM bla' 737 738 Args: 739 expression (str | Expression): the SQL code string. 740 If an `Expression` instance is passed, it will be used as-is. 741 distinct (bool): set the DISTINCT flag if and only if this is true. 742 dialect (str): the dialect used to parse the input expression. 743 opts (kwargs): other options to use to parse the input expressions. 744 Returns: 745 Intersect: the Intersect expression 746 """ 747 return intersect(left=self, right=expression, distinct=distinct, dialect=dialect, **opts) 748 749 def except_(self, expression, distinct=True, dialect=None, **opts): 750 """ 751 Builds an EXCEPT expression. 752 753 Example: 754 >>> import sqlglot 755 >>> sqlglot.parse_one("SELECT * FROM foo").except_("SELECT * FROM bla").sql() 756 'SELECT * FROM foo EXCEPT SELECT * FROM bla' 757 758 Args: 759 expression (str | Expression): the SQL code string. 760 If an `Expression` instance is passed, it will be used as-is. 761 distinct (bool): set the DISTINCT flag if and only if this is true. 762 dialect (str): the dialect used to parse the input expression. 763 opts (kwargs): other options to use to parse the input expressions. 764 Returns: 765 Except: the Except expression 766 """ 767 return except_(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
def
union(self, expression, distinct=True, dialect=None, **opts):
709 def union(self, expression, distinct=True, dialect=None, **opts): 710 """ 711 Builds a UNION expression. 712 713 Example: 714 >>> import sqlglot 715 >>> sqlglot.parse_one("SELECT * FROM foo").union("SELECT * FROM bla").sql() 716 'SELECT * FROM foo UNION SELECT * FROM bla' 717 718 Args: 719 expression (str | Expression): the SQL code string. 720 If an `Expression` instance is passed, it will be used as-is. 721 distinct (bool): set the DISTINCT flag if and only if this is true. 722 dialect (str): the dialect used to parse the input expression. 723 opts (kwargs): other options to use to parse the input expressions. 724 Returns: 725 Union: the Union expression. 726 """ 727 return union(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
Builds a UNION expression.
Example:
>>> import sqlglot >>> sqlglot.parse_one("SELECT * FROM foo").union("SELECT * FROM bla").sql() 'SELECT * FROM foo UNION SELECT * FROM bla'
Arguments:
- expression (str | Expression): the SQL code string.
If an
Expressioninstance is passed, it will be used as-is. - distinct (bool): set the DISTINCT flag if and only if this is true.
- dialect (str): the dialect used to parse the input expression.
- opts (kwargs): other options to use to parse the input expressions.
Returns:
Union: the Union expression.
def
intersect(self, expression, distinct=True, dialect=None, **opts):
729 def intersect(self, expression, distinct=True, dialect=None, **opts): 730 """ 731 Builds an INTERSECT expression. 732 733 Example: 734 >>> import sqlglot 735 >>> sqlglot.parse_one("SELECT * FROM foo").intersect("SELECT * FROM bla").sql() 736 'SELECT * FROM foo INTERSECT SELECT * FROM bla' 737 738 Args: 739 expression (str | Expression): the SQL code string. 740 If an `Expression` instance is passed, it will be used as-is. 741 distinct (bool): set the DISTINCT flag if and only if this is true. 742 dialect (str): the dialect used to parse the input expression. 743 opts (kwargs): other options to use to parse the input expressions. 744 Returns: 745 Intersect: the Intersect expression 746 """ 747 return intersect(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
Builds an INTERSECT expression.
Example:
>>> import sqlglot >>> sqlglot.parse_one("SELECT * FROM foo").intersect("SELECT * FROM bla").sql() 'SELECT * FROM foo INTERSECT SELECT * FROM bla'
Arguments:
- expression (str | Expression): the SQL code string.
If an
Expressioninstance is passed, it will be used as-is. - distinct (bool): set the DISTINCT flag if and only if this is true.
- dialect (str): the dialect used to parse the input expression.
- opts (kwargs): other options to use to parse the input expressions.
Returns:
Intersect: the Intersect expression
def
except_(self, expression, distinct=True, dialect=None, **opts):
749 def except_(self, expression, distinct=True, dialect=None, **opts): 750 """ 751 Builds an EXCEPT expression. 752 753 Example: 754 >>> import sqlglot 755 >>> sqlglot.parse_one("SELECT * FROM foo").except_("SELECT * FROM bla").sql() 756 'SELECT * FROM foo EXCEPT SELECT * FROM bla' 757 758 Args: 759 expression (str | Expression): the SQL code string. 760 If an `Expression` instance is passed, it will be used as-is. 761 distinct (bool): set the DISTINCT flag if and only if this is true. 762 dialect (str): the dialect used to parse the input expression. 763 opts (kwargs): other options to use to parse the input expressions. 764 Returns: 765 Except: the Except expression 766 """ 767 return except_(left=self, right=expression, distinct=distinct, dialect=dialect, **opts)
Builds an EXCEPT expression.
Example:
>>> import sqlglot >>> sqlglot.parse_one("SELECT * FROM foo").except_("SELECT * FROM bla").sql() 'SELECT * FROM foo EXCEPT SELECT * FROM bla'
Arguments:
- expression (str | Expression): the SQL code string.
If an
Expressioninstance is passed, it will be used as-is. - distinct (bool): set the DISTINCT flag if and only if this is true.
- dialect (str): the dialect used to parse the input expression.
- opts (kwargs): other options to use to parse the input expressions.
Returns:
Except: the Except expression
Inherited Members
Inherited Members
774class Cache(Expression): 775 arg_types = { 776 "with": False, 777 "this": True, 778 "lazy": False, 779 "options": False, 780 "expression": False, 781 }
Inherited Members
Inherited Members
788class Create(Expression): 789 arg_types = { 790 "with": False, 791 "this": True, 792 "kind": True, 793 "expression": False, 794 "exists": False, 795 "properties": False, 796 "replace": False, 797 "unique": False, 798 "indexes": False, 799 "no_schema_binding": False, 800 "begin": False, 801 }
Inherited Members
Inherited Members
Inherited Members
812class SetItem(Expression): 813 arg_types = { 814 "this": False, 815 "expressions": False, 816 "kind": False, 817 "collate": False, # MySQL SET NAMES statement 818 "global": False, 819 }
Inherited Members
822class Show(Expression): 823 arg_types = { 824 "this": True, 825 "target": False, 826 "offset": False, 827 "limit": False, 828 "like": False, 829 "where": False, 830 "db": False, 831 "full": False, 832 "mutex": False, 833 "query": False, 834 "channel": False, 835 "global": False, 836 "log": False, 837 "position": False, 838 "types": False, 839 }
Inherited Members
842class UserDefinedFunction(Expression): 843 arg_types = {"this": True, "expressions": False, "wrapped": False}
Inherited Members
Inherited Members
850class With(Expression): 851 arg_types = {"expressions": True, "recursive": False} 852 853 @property 854 def recursive(self) -> bool: 855 return bool(self.args.get("recursive"))
Inherited Members
Inherited Members
Inherited Members
866class TableAlias(Expression): 867 arg_types = {"this": False, "columns": False} 868 869 @property 870 def columns(self): 871 return self.args.get("columns") or []
Inherited Members
Inherited Members
Inherited Members
Inherited Members
886class Column(Condition): 887 arg_types = {"this": True, "table": False, "db": False, "catalog": False} 888 889 @property 890 def table(self) -> str: 891 return self.text("table") 892 893 @property 894 def db(self) -> str: 895 return self.text("db") 896 897 @property 898 def catalog(self) -> str: 899 return self.text("catalog") 900 901 @property 902 def output_name(self) -> str: 903 return self.name
output_name: str
Name of the output column if this expression is a selection.
If the Expression has no output name, an empty string is returned.
Example:
>>> from sqlglot import parse_one >>> parse_one("SELECT a").expressions[0].output_name 'a' >>> parse_one("SELECT b AS c").expressions[0].output_name 'c' >>> parse_one("SELECT 1 + 2").expressions[0].output_name ''
Inherited Members
906class ColumnDef(Expression): 907 arg_types = { 908 "this": True, 909 "kind": False, 910 "constraints": False, 911 "exists": False, 912 }
Inherited Members
915class AlterColumn(Expression): 916 arg_types = { 917 "this": True, 918 "dtype": False, 919 "collate": False, 920 "using": False, 921 "default": False, 922 "drop": False, 923 }
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
978class GeneratedAsIdentityColumnConstraint(ColumnConstraintKind): 979 # this: True -> ALWAYS, this: False -> BY DEFAULT 980 arg_types = { 981 "this": False, 982 "start": False, 983 "increment": False, 984 "minvalue": False, 985 "maxvalue": False, 986 "cycle": False, 987 }
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
1022class Delete(Expression): 1023 arg_types = {"with": False, "this": False, "using": False, "where": False}
Inherited Members
1026class Drop(Expression): 1027 arg_types = { 1028 "this": False, 1029 "kind": False, 1030 "exists": False, 1031 "temporary": False, 1032 "materialized": False, 1033 "cascade": False, 1034 }
Inherited Members
Inherited Members
Inherited Members
1045class Directory(Expression): 1046 # https://spark.apache.org/docs/3.0.0-preview/sql-ref-syntax-dml-insert-overwrite-directory-hive.html 1047 arg_types = {"this": True, "local": False, "row_format": False}
Inherited Members
1050class ForeignKey(Expression): 1051 arg_types = { 1052 "expressions": True, 1053 "reference": False, 1054 "delete": False, 1055 "update": False, 1056 }
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
1089class Identifier(Expression): 1090 arg_types = {"this": True, "quoted": False} 1091 1092 @property 1093 def quoted(self): 1094 return bool(self.args.get("quoted")) 1095 1096 def __eq__(self, other): 1097 return isinstance(other, self.__class__) and _norm_arg(self.this) == _norm_arg(other.this) 1098 1099 def __hash__(self): 1100 return hash((self.key, self.this.lower())) 1101 1102 @property 1103 def output_name(self): 1104 return self.name
output_name
Name of the output column if this expression is a selection.
If the Expression has no output name, an empty string is returned.
Example:
>>> from sqlglot import parse_one >>> parse_one("SELECT a").expressions[0].output_name 'a' >>> parse_one("SELECT b AS c").expressions[0].output_name 'c' >>> parse_one("SELECT 1 + 2").expressions[0].output_name ''
1107class Index(Expression): 1108 arg_types = { 1109 "this": False, 1110 "table": False, 1111 "where": False, 1112 "columns": False, 1113 "unique": False, 1114 "primary": False, 1115 "amp": False, # teradata 1116 }
Inherited Members
1119class Insert(Expression): 1120 arg_types = { 1121 "with": False, 1122 "this": True, 1123 "expression": False, 1124 "overwrite": False, 1125 "exists": False, 1126 "partition": False, 1127 "alternative": False, 1128 }
Inherited Members
Inherited Members
Inherited Members
1141class LoadData(Expression): 1142 arg_types = { 1143 "this": True, 1144 "local": False, 1145 "overwrite": False, 1146 "inpath": True, 1147 "partition": False, 1148 "input_format": False, 1149 "serde": False, 1150 }
Inherited Members
Inherited Members
Inherited Members
1161class Group(Expression): 1162 arg_types = { 1163 "expressions": False, 1164 "grouping_sets": False, 1165 "cube": False, 1166 "rollup": False, 1167 }
Inherited Members
Inherited Members
Inherited Members
1178class Literal(Condition): 1179 arg_types = {"this": True, "is_string": True} 1180 1181 def __eq__(self, other): 1182 return ( 1183 isinstance(other, Literal) 1184 and self.this == other.this 1185 and self.args["is_string"] == other.args["is_string"] 1186 ) 1187 1188 def __hash__(self): 1189 return hash((self.key, self.this, self.args["is_string"])) 1190 1191 @classmethod 1192 def number(cls, number) -> Literal: 1193 return cls(this=str(number), is_string=False) 1194 1195 @classmethod 1196 def string(cls, string) -> Literal: 1197 return cls(this=str(string), is_string=True) 1198 1199 @property 1200 def output_name(self): 1201 return self.name
output_name
Name of the output column if this expression is a selection.
If the Expression has no output name, an empty string is returned.
Example:
>>> from sqlglot import parse_one >>> parse_one("SELECT a").expressions[0].output_name 'a' >>> parse_one("SELECT b AS c").expressions[0].output_name 'c' >>> parse_one("SELECT 1 + 2").expressions[0].output_name ''
Inherited Members
1204class Join(Expression): 1205 arg_types = { 1206 "this": True, 1207 "on": False, 1208 "side": False, 1209 "kind": False, 1210 "using": False, 1211 "natural": False, 1212 } 1213 1214 @property 1215 def kind(self): 1216 return self.text("kind").upper() 1217 1218 @property 1219 def side(self): 1220 return self.text("side").upper() 1221 1222 @property 1223 def alias_or_name(self): 1224 return self.this.alias_or_name 1225 1226 def on(self, *expressions, append=True, dialect=None, copy=True, **opts): 1227 """ 1228 Append to or set the ON expressions. 1229 1230 Example: 1231 >>> import sqlglot 1232 >>> sqlglot.parse_one("JOIN x", into=Join).on("y = 1").sql() 1233 'JOIN x ON y = 1' 1234 1235 Args: 1236 *expressions (str | Expression): the SQL code strings to parse. 1237 If an `Expression` instance is passed, it will be used as-is. 1238 Multiple expressions are combined with an AND operator. 1239 append (bool): if `True`, AND the new expressions to any existing expression. 1240 Otherwise, this resets the expression. 1241 dialect (str): the dialect used to parse the input expressions. 1242 copy (bool): if `False`, modify this expression instance in-place. 1243 opts (kwargs): other options to use to parse the input expressions. 1244 1245 Returns: 1246 Join: the modified join expression. 1247 """ 1248 join = _apply_conjunction_builder( 1249 *expressions, 1250 instance=self, 1251 arg="on", 1252 append=append, 1253 dialect=dialect, 1254 copy=copy, 1255 **opts, 1256 ) 1257 1258 if join.kind == "CROSS": 1259 join.set("kind", None) 1260 1261 return join 1262 1263 def using(self, *expressions, append=True, dialect=None, copy=True, **opts): 1264 """ 1265 Append to or set the USING expressions. 1266 1267 Example: 1268 >>> import sqlglot 1269 >>> sqlglot.parse_one("JOIN x", into=Join).using("foo", "bla").sql() 1270 'JOIN x USING (foo, bla)' 1271 1272 Args: 1273 *expressions (str | Expression): the SQL code strings to parse. 1274 If an `Expression` instance is passed, it will be used as-is. 1275 append (bool): if `True`, concatenate the new expressions to the existing "using" list. 1276 Otherwise, this resets the expression. 1277 dialect (str): the dialect used to parse the input expressions. 1278 copy (bool): if `False`, modify this expression instance in-place. 1279 opts (kwargs): other options to use to parse the input expressions. 1280 1281 Returns: 1282 Join: the modified join expression. 1283 """ 1284 join = _apply_list_builder( 1285 *expressions, 1286 instance=self, 1287 arg="using", 1288 append=append, 1289 dialect=dialect, 1290 copy=copy, 1291 **opts, 1292 ) 1293 1294 if join.kind == "CROSS": 1295 join.set("kind", None) 1296 1297 return join
def
on(self, *expressions, append=True, dialect=None, copy=True, **opts):
1226 def on(self, *expressions, append=True, dialect=None, copy=True, **opts): 1227 """ 1228 Append to or set the ON expressions. 1229 1230 Example: 1231 >>> import sqlglot 1232 >>> sqlglot.parse_one("JOIN x", into=Join).on("y = 1").sql() 1233 'JOIN x ON y = 1' 1234 1235 Args: 1236 *expressions (str | Expression): the SQL code strings to parse. 1237 If an `Expression` instance is passed, it will be used as-is. 1238 Multiple expressions are combined with an AND operator. 1239 append (bool): if `True`, AND the new expressions to any existing expression. 1240 Otherwise, this resets the expression. 1241 dialect (str): the dialect used to parse the input expressions. 1242 copy (bool): if `False`, modify this expression instance in-place. 1243 opts (kwargs): other options to use to parse the input expressions. 1244 1245 Returns: 1246 Join: the modified join expression. 1247 """ 1248 join = _apply_conjunction_builder( 1249 *expressions, 1250 instance=self, 1251 arg="on", 1252 append=append, 1253 dialect=dialect, 1254 copy=copy, 1255 **opts, 1256 ) 1257 1258 if join.kind == "CROSS": 1259 join.set("kind", None) 1260 1261 return join
Append to or set the ON expressions.
Example:
>>> import sqlglot >>> sqlglot.parse_one("JOIN x", into=Join).on("y = 1").sql() 'JOIN x ON y = 1'
Arguments:
- *expressions (str | Expression): the SQL code strings to parse.
If an
Expressioninstance is passed, it will be used as-is. Multiple expressions are combined with an AND operator. - append (bool): if
True, AND the new expressions to any existing expression. Otherwise, this resets the expression. - dialect (str): the dialect used to parse the input expressions.
- copy (bool): if
False, modify this expression instance in-place. - opts (kwargs): other options to use to parse the input expressions.
Returns:
Join: the modified join expression.
def
using(self, *expressions, append=True, dialect=None, copy=True, **opts):
1263 def using(self, *expressions, append=True, dialect=None, copy=True, **opts): 1264 """ 1265 Append to or set the USING expressions. 1266 1267 Example: 1268 >>> import sqlglot 1269 >>> sqlglot.parse_one("JOIN x", into=Join).using("foo", "bla").sql() 1270 'JOIN x USING (foo, bla)' 1271 1272 Args: 1273 *expressions (str | Expression): the SQL code strings to parse. 1274 If an `Expression` instance is passed, it will be used as-is. 1275 append (bool): if `True`, concatenate the new expressions to the existing "using" list. 1276 Otherwise, this resets the expression. 1277 dialect (str): the dialect used to parse the input expressions. 1278 copy (bool): if `False`, modify this expression instance in-place. 1279 opts (kwargs): other options to use to parse the input expressions. 1280 1281 Returns: 1282 Join: the modified join expression. 1283 """ 1284 join = _apply_list_builder( 1285 *expressions, 1286 instance=self, 1287 arg="using", 1288 append=append, 1289 dialect=dialect, 1290 copy=copy, 1291 **opts, 1292 ) 1293 1294 if join.kind == "CROSS": 1295 join.set("kind", None) 1296 1297 return join
Append to or set the USING expressions.
Example:
>>> import sqlglot >>> sqlglot.parse_one("JOIN x", into=Join).using("foo", "bla").sql() 'JOIN x USING (foo, bla)'
Arguments:
- *expressions (str | Expression): the SQL code strings to parse.
If an
Expressioninstance is passed, it will be used as-is. - append (bool): if
True, concatenate the new expressions to the existing "using" list. Otherwise, this resets the expression. - dialect (str): the dialect used to parse the input expressions.
- copy (bool): if
False, modify this expression instance in-place. - opts (kwargs): other options to use to parse the input expressions.
Returns:
Join: the modified join expression.
Inherited Members
1300class Lateral(UDTF): 1301 arg_types = {"this": True, "view": False, "outer": False, "alias": False}
Inherited Members
1304class MatchRecognize(Expression): 1305 arg_types = { 1306 "partition_by": False, 1307 "order": False, 1308 "measures": False, 1309 "rows": False, 1310 "after": False, 1311 "pattern": False, 1312 "define": False, 1313 }
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
1352class AfterJournalProperty(Property): 1353 arg_types = {"no": True, "dual": False, "local": False}
Inherited Members
Inherited Members
Inherited Members
1364class BlockCompressionProperty(Property): 1365 arg_types = {"autotemp": False, "always": False, "default": True, "manual": True, "never": True}
Inherited Members
Inherited Members
Inherited Members
Inherited Members
1380class DataBlocksizeProperty(Property): 1381 arg_types = {"size": False, "units": False, "min": False, "default": False}
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
1420class IsolatedLoadingProperty(Property): 1421 arg_types = { 1422 "no": True, 1423 "concurrent": True, 1424 "for_all": True, 1425 "for_insert": True, 1426 "for_none": True, 1427 }
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
1446class LockingProperty(Property): 1447 arg_types = { 1448 "this": False, 1449 "kind": True, 1450 "for_or_in": True, 1451 "lock_type": True, 1452 "override": False, 1453 }
Inherited Members
Inherited Members
Inherited Members
1464class MergeBlockRatioProperty(Property): 1465 arg_types = {"this": False, "no": False, "default": False, "percent": False}
Inherited Members
Inherited Members
Inherited Members
Inherited Members
1480class ReturnsProperty(Property): 1481 arg_types = {"this": True, "is_table": False, "table": False}
Inherited Members
1484class RowFormatDelimitedProperty(Property): 1485 # https://cwiki.apache.org/confluence/display/hive/languagemanual+dml 1486 arg_types = { 1487 "fields": False, 1488 "escaped": False, 1489 "collection_items": False, 1490 "map_keys": False, 1491 "lines": False, 1492 "null": False, 1493 "serde": False, 1494 }
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
1545class Properties(Expression): 1546 arg_types = {"expressions": True} 1547 1548 NAME_TO_PROPERTY = { 1549 "ALGORITHM": AlgorithmProperty, 1550 "AUTO_INCREMENT": AutoIncrementProperty, 1551 "CHARACTER SET": CharacterSetProperty, 1552 "COLLATE": CollateProperty, 1553 "COMMENT": SchemaCommentProperty, 1554 "DEFINER": DefinerProperty, 1555 "DISTKEY": DistKeyProperty, 1556 "DISTSTYLE": DistStyleProperty, 1557 "ENGINE": EngineProperty, 1558 "EXECUTE AS": ExecuteAsProperty, 1559 "FORMAT": FileFormatProperty, 1560 "LANGUAGE": LanguageProperty, 1561 "LOCATION": LocationProperty, 1562 "PARTITIONED_BY": PartitionedByProperty, 1563 "RETURNS": ReturnsProperty, 1564 "SORTKEY": SortKeyProperty, 1565 "TABLE_FORMAT": TableFormatProperty, 1566 } 1567 1568 PROPERTY_TO_NAME = {v: k for k, v in NAME_TO_PROPERTY.items()} 1569 1570 # CREATE property locations 1571 # Form: schema specified 1572 # create [POST_CREATE] 1573 # table a [POST_NAME] 1574 # (b int) [POST_SCHEMA] 1575 # with ([POST_WITH]) 1576 # index (b) [POST_INDEX] 1577 # 1578 # Form: alias selection 1579 # create [POST_CREATE] 1580 # table a [POST_NAME] 1581 # as [POST_ALIAS] (select * from b) [POST_EXPRESSION] 1582 # index (c) [POST_INDEX] 1583 class Location(AutoName): 1584 POST_CREATE = auto() 1585 POST_NAME = auto() 1586 POST_SCHEMA = auto() 1587 POST_WITH = auto() 1588 POST_ALIAS = auto() 1589 POST_EXPRESSION = auto() 1590 POST_INDEX = auto() 1591 UNSUPPORTED = auto() 1592 1593 @classmethod 1594 def from_dict(cls, properties_dict) -> Properties: 1595 expressions = [] 1596 for key, value in properties_dict.items(): 1597 property_cls = cls.NAME_TO_PROPERTY.get(key.upper()) 1598 if property_cls: 1599 expressions.append(property_cls(this=convert(value))) 1600 else: 1601 expressions.append(Property(this=Literal.string(key), value=convert(value))) 1602 1603 return cls(expressions=expressions)
1593 @classmethod 1594 def from_dict(cls, properties_dict) -> Properties: 1595 expressions = [] 1596 for key, value in properties_dict.items(): 1597 property_cls = cls.NAME_TO_PROPERTY.get(key.upper()) 1598 if property_cls: 1599 expressions.append(property_cls(this=convert(value))) 1600 else: 1601 expressions.append(Property(this=Literal.string(key), value=convert(value))) 1602 1603 return cls(expressions=expressions)
Inherited Members
1583 class Location(AutoName): 1584 POST_CREATE = auto() 1585 POST_NAME = auto() 1586 POST_SCHEMA = auto() 1587 POST_WITH = auto() 1588 POST_ALIAS = auto() 1589 POST_EXPRESSION = auto() 1590 POST_INDEX = auto() 1591 UNSUPPORTED = auto()
An enumeration.
Inherited Members
- enum.Enum
- name
- value
Inherited Members
Inherited Members
1615class Reference(Expression): 1616 arg_types = {"this": True, "expressions": False, "options": False}
Inherited Members
Inherited Members
1623class Subqueryable(Unionable): 1624 def subquery(self, alias=None, copy=True) -> Subquery: 1625 """ 1626 Convert this expression to an aliased expression that can be used as a Subquery. 1627 1628 Example: 1629 >>> subquery = Select().select("x").from_("tbl").subquery() 1630 >>> Select().select("x").from_(subquery).sql() 1631 'SELECT x FROM (SELECT x FROM tbl)' 1632 1633 Args: 1634 alias (str | Identifier): an optional alias for the subquery 1635 copy (bool): if `False`, modify this expression instance in-place. 1636 1637 Returns: 1638 Alias: the subquery 1639 """ 1640 instance = _maybe_copy(self, copy) 1641 return Subquery( 1642 this=instance, 1643 alias=TableAlias(this=to_identifier(alias)), 1644 ) 1645 1646 def limit(self, expression, dialect=None, copy=True, **opts) -> Select: 1647 raise NotImplementedError 1648 1649 @property 1650 def ctes(self): 1651 with_ = self.args.get("with") 1652 if not with_: 1653 return [] 1654 return with_.expressions 1655 1656 @property 1657 def selects(self): 1658 raise NotImplementedError("Subqueryable objects must implement `selects`") 1659 1660 @property 1661 def named_selects(self): 1662 raise NotImplementedError("Subqueryable objects must implement `named_selects`") 1663 1664 def with_( 1665 self, 1666 alias, 1667 as_, 1668 recursive=None, 1669 append=True, 1670 dialect=None, 1671 copy=True, 1672 **opts, 1673 ): 1674 """ 1675 Append to or set the common table expressions. 1676 1677 Example: 1678 >>> Select().with_("tbl2", as_="SELECT * FROM tbl").select("x").from_("tbl2").sql() 1679 'WITH tbl2 AS (SELECT * FROM tbl) SELECT x FROM tbl2' 1680 1681 Args: 1682 alias (str | Expression): the SQL code string to parse as the table name. 1683 If an `Expression` instance is passed, this is used as-is. 1684 as_ (str | Expression): the SQL code string to parse as the table expression. 1685 If an `Expression` instance is passed, it will be used as-is. 1686 recursive (bool): set the RECURSIVE part of the expression. Defaults to `False`. 1687 append (bool): if `True`, add to any existing expressions. 1688 Otherwise, this resets the expressions. 1689 dialect (str): the dialect used to parse the input expression. 1690 copy (bool): if `False`, modify this expression instance in-place. 1691 opts (kwargs): other options to use to parse the input expressions. 1692 1693 Returns: 1694 Select: the modified expression. 1695 """ 1696 alias_expression = maybe_parse( 1697 alias, 1698 dialect=dialect, 1699 into=TableAlias, 1700 **opts, 1701 ) 1702 as_expression = maybe_parse( 1703 as_, 1704 dialect=dialect, 1705 **opts, 1706 ) 1707 cte = CTE( 1708 this=as_expression, 1709 alias=alias_expression, 1710 ) 1711 return _apply_child_list_builder( 1712 cte, 1713 instance=self, 1714 arg="with", 1715 append=append, 1716 copy=copy, 1717 into=With, 1718 properties={"recursive": recursive or False}, 1719 )
1624 def subquery(self, alias=None, copy=True) -> Subquery: 1625 """ 1626 Convert this expression to an aliased expression that can be used as a Subquery. 1627 1628 Example: 1629 >>> subquery = Select().select("x").from_("tbl").subquery() 1630 >>> Select().select("x").from_(subquery).sql() 1631 'SELECT x FROM (SELECT x FROM tbl)' 1632 1633 Args: 1634 alias (str | Identifier): an optional alias for the subquery 1635 copy (bool): if `False`, modify this expression instance in-place. 1636 1637 Returns: 1638 Alias: the subquery 1639 """ 1640 instance = _maybe_copy(self, copy) 1641 return Subquery( 1642 this=instance, 1643 alias=TableAlias(this=to_identifier(alias)), 1644 )
Convert this expression to an aliased expression that can be used as a Subquery.
Example:
>>> subquery = Select().select("x").from_("tbl").subquery() >>> Select().select("x").from_(subquery).sql() 'SELECT x FROM (SELECT x FROM tbl)'
Arguments:
- alias (str | Identifier): an optional alias for the subquery
- copy (bool): if
False, modify this expression instance in-place.
Returns:
Alias: the subquery
def
with_( self, alias, as_, recursive=None, append=True, dialect=None, copy=True, **opts):
1664 def with_( 1665 self, 1666 alias, 1667 as_, 1668 recursive=None, 1669 append=True, 1670 dialect=None, 1671 copy=True, 1672 **opts, 1673 ): 1674 """ 1675 Append to or set the common table expressions. 1676 1677 Example: 1678 >>> Select().with_("tbl2", as_="SELECT * FROM tbl").select("x").from_("tbl2").sql() 1679 'WITH tbl2 AS (SELECT * FROM tbl) SELECT x FROM tbl2' 1680 1681 Args: 1682 alias (str | Expression): the SQL code string to parse as the table name. 1683 If an `Expression` instance is passed, this is used as-is. 1684 as_ (str | Expression): the SQL code string to parse as the table expression. 1685 If an `Expression` instance is passed, it will be used as-is. 1686 recursive (bool): set the RECURSIVE part of the expression. Defaults to `False`. 1687 append (bool): if `True`, add to any existing expressions. 1688 Otherwise, this resets the expressions. 1689 dialect (str): the dialect used to parse the input expression. 1690 copy (bool): if `False`, modify this expression instance in-place. 1691 opts (kwargs): other options to use to parse the input expressions. 1692 1693 Returns: 1694 Select: the modified expression. 1695 """ 1696 alias_expression = maybe_parse( 1697 alias, 1698 dialect=dialect, 1699 into=TableAlias, 1700 **opts, 1701 ) 1702 as_expression = maybe_parse( 1703 as_, 1704 dialect=dialect, 1705 **opts, 1706 ) 1707 cte = CTE( 1708 this=as_expression, 1709 alias=alias_expression, 1710 ) 1711 return _apply_child_list_builder( 1712 cte, 1713 instance=self, 1714 arg="with", 1715 append=append, 1716 copy=copy, 1717 into=With, 1718 properties={"recursive": recursive or False}, 1719 )
Append to or set the common table expressions.
Example:
>>> Select().with_("tbl2", as_="SELECT * FROM tbl").select("x").from_("tbl2").sql() 'WITH tbl2 AS (SELECT * FROM tbl) SELECT x FROM tbl2'
Arguments:
- alias (str | Expression): the SQL code string to parse as the table name.
If an
Expressioninstance is passed, this is used as-is. - as_ (str | Expression): the SQL code string to parse as the table expression.
If an
Expressioninstance is passed, it will be used as-is. - recursive (bool): set the RECURSIVE part of the expression. Defaults to
False. - append (bool): if
True, add to any existing expressions. Otherwise, this resets the expressions. - dialect (str): the dialect used to parse the input expression.
- copy (bool): if
False, modify this expression instance in-place. - opts (kwargs): other options to use to parse the input expressions.
Returns:
Select: the modified expression.
Inherited Members
1742class Table(Expression): 1743 arg_types = { 1744 "this": True, 1745 "alias": False, 1746 "db": False, 1747 "catalog": False, 1748 "laterals": False, 1749 "joins": False, 1750 "pivots": False, 1751 "hints": False, 1752 "system_time": False, 1753 } 1754 1755 @property 1756 def db(self) -> str: 1757 return self.text("db") 1758 1759 @property 1760 def catalog(self) -> str: 1761 return self.text("catalog")
Inherited Members
1765class SystemTime(Expression): 1766 arg_types = { 1767 "this": False, 1768 "expression": False, 1769 "kind": True, 1770 }
Inherited Members
1773class Union(Subqueryable): 1774 arg_types = { 1775 "with": False, 1776 "this": True, 1777 "expression": True, 1778 "distinct": False, 1779 **QUERY_MODIFIERS, 1780 } 1781 1782 def limit(self, expression, dialect=None, copy=True, **opts) -> Select: 1783 """ 1784 Set the LIMIT expression. 1785 1786 Example: 1787 >>> select("1").union(select("1")).limit(1).sql() 1788 'SELECT * FROM (SELECT 1 UNION SELECT 1) AS _l_0 LIMIT 1' 1789 1790 Args: 1791 expression (str | int | Expression): the SQL code string to parse. 1792 This can also be an integer. 1793 If a `Limit` instance is passed, this is used as-is. 1794 If another `Expression` instance is passed, it will be wrapped in a `Limit`. 1795 dialect (str): the dialect used to parse the input expression. 1796 copy (bool): if `False`, modify this expression instance in-place. 1797 opts (kwargs): other options to use to parse the input expressions. 1798 1799 Returns: 1800 Select: The limited subqueryable. 1801 """ 1802 return ( 1803 select("*") 1804 .from_(self.subquery(alias="_l_0", copy=copy)) 1805 .limit(expression, dialect=dialect, copy=False, **opts) 1806 ) 1807 1808 def select( 1809 self, 1810 *expressions: str | Expression, 1811 append: bool = True, 1812 dialect: DialectType = None, 1813 copy: bool = True, 1814 **opts, 1815 ) -> Union: 1816 """Append to or set the SELECT of the union recursively. 1817 1818 Example: 1819 >>> from sqlglot import parse_one 1820 >>> parse_one("select a from x union select a from y union select a from z").select("b").sql() 1821 'SELECT a, b FROM x UNION SELECT a, b FROM y UNION SELECT a, b FROM z' 1822 1823 Args: 1824 *expressions: the SQL code strings to parse. 1825 If an `Expression` instance is passed, it will be used as-is. 1826 append: if `True`, add to any existing expressions. 1827 Otherwise, this resets the expressions. 1828 dialect: the dialect used to parse the input expressions. 1829 copy: if `False`, modify this expression instance in-place. 1830 opts: other options to use to parse the input expressions. 1831 1832 Returns: 1833 Union: the modified expression. 1834 """ 1835 this = self.copy() if copy else self 1836 this.this.unnest().select(*expressions, append=append, dialect=dialect, copy=False, **opts) 1837 this.expression.unnest().select( 1838 *expressions, append=append, dialect=dialect, copy=False, **opts 1839 ) 1840 return this 1841 1842 @property 1843 def named_selects(self): 1844 return self.this.unnest().named_selects 1845 1846 @property 1847 def is_star(self) -> bool: 1848 return self.this.is_star or self.expression.is_star 1849 1850 @property 1851 def selects(self): 1852 return self.this.unnest().selects 1853 1854 @property 1855 def left(self): 1856 return self.this 1857 1858 @property 1859 def right(self): 1860 return self.expression
1782 def limit(self, expression, dialect=None, copy=True, **opts) -> Select: 1783 """ 1784 Set the LIMIT expression. 1785 1786 Example: 1787 >>> select("1").union(select("1")).limit(1).sql() 1788 'SELECT * FROM (SELECT 1 UNION SELECT 1) AS _l_0 LIMIT 1' 1789 1790 Args: 1791 expression (str | int | Expression): the SQL code string to parse. 1792 This can also be an integer. 1793 If a `Limit` instance is passed, this is used as-is. 1794 If another `Expression` instance is passed, it will be wrapped in a `Limit`. 1795 dialect (str): the dialect used to parse the input expression. 1796 copy (bool): if `False`, modify this expression instance in-place. 1797 opts (kwargs): other options to use to parse the input expressions. 1798 1799 Returns: 1800 Select: The limited subqueryable. 1801 """ 1802 return ( 1803 select("*") 1804 .from_(self.subquery(alias="_l_0", copy=copy)) 1805 .limit(expression, dialect=dialect, copy=False, **opts) 1806 )
Set the LIMIT expression.
Example:
>>> select("1").union(select("1")).limit(1).sql() 'SELECT * FROM (SELECT 1 UNION SELECT 1) AS _l_0 LIMIT 1'
Arguments:
- expression (str | int | Expression): the SQL code string to parse.
This can also be an integer.
If a
Limitinstance is passed, this is used as-is. If anotherExpressioninstance is passed, it will be wrapped in aLimit. - dialect (str): the dialect used to parse the input expression.
- copy (bool): if
False, modify this expression instance in-place. - opts (kwargs): other options to use to parse the input expressions.
Returns:
Select: The limited subqueryable.
def
select( self, *expressions: str | sqlglot.expressions.Expression, append: bool = True, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> sqlglot.expressions.Union:
1808 def select( 1809 self, 1810 *expressions: str | Expression, 1811 append: bool = True, 1812 dialect: DialectType = None, 1813 copy: bool = True, 1814 **opts, 1815 ) -> Union: 1816 """Append to or set the SELECT of the union recursively. 1817 1818 Example: 1819 >>> from sqlglot import parse_one 1820 >>> parse_one("select a from x union select a from y union select a from z").select("b").sql() 1821 'SELECT a, b FROM x UNION SELECT a, b FROM y UNION SELECT a, b FROM z' 1822 1823 Args: 1824 *expressions: the SQL code strings to parse. 1825 If an `Expression` instance is passed, it will be used as-is. 1826 append: if `True`, add to any existing expressions. 1827 Otherwise, this resets the expressions. 1828 dialect: the dialect used to parse the input expressions. 1829 copy: if `False`, modify this expression instance in-place. 1830 opts: other options to use to parse the input expressions. 1831 1832 Returns: 1833 Union: the modified expression. 1834 """ 1835 this = self.copy() if copy else self 1836 this.this.unnest().select(*expressions, append=append, dialect=dialect, copy=False, **opts) 1837 this.expression.unnest().select( 1838 *expressions, append=append, dialect=dialect, copy=False, **opts 1839 ) 1840 return this
Append to or set the SELECT of the union recursively.
Example:
>>> from sqlglot import parse_one >>> parse_one("select a from x union select a from y union select a from z").select("b").sql() 'SELECT a, b FROM x UNION SELECT a, b FROM y UNION SELECT a, b FROM z'
Arguments:
- *expressions: the SQL code strings to parse.
If an
Expressioninstance is passed, it will be used as-is. - append: if
True, add to any existing expressions. Otherwise, this resets the expressions. - dialect: the dialect used to parse the input expressions.
- copy: if
False, modify this expression instance in-place. - opts: other options to use to parse the input expressions.
Returns:
Union: the modified expression.
Inherited Members
Inherited Members
Inherited Members
1871class Unnest(UDTF): 1872 arg_types = { 1873 "expressions": True, 1874 "ordinality": False, 1875 "alias": False, 1876 "offset": False, 1877 }
Inherited Members
1880class Update(Expression): 1881 arg_types = { 1882 "with": False, 1883 "this": False, 1884 "expressions": True, 1885 "from": False, 1886 "where": False, 1887 }
Inherited Members
1890class Values(UDTF): 1891 arg_types = { 1892 "expressions": True, 1893 "ordinality": False, 1894 "alias": False, 1895 }
Inherited Members
Inherited Members
Inherited Members
Inherited Members
1912class Select(Subqueryable): 1913 arg_types = { 1914 "with": False, 1915 "expressions": False, 1916 "hint": False, 1917 "distinct": False, 1918 "into": False, 1919 "from": False, 1920 **QUERY_MODIFIERS, 1921 } 1922 1923 def from_(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 1924 """ 1925 Set the FROM expression. 1926 1927 Example: 1928 >>> Select().from_("tbl").select("x").sql() 1929 'SELECT x FROM tbl' 1930 1931 Args: 1932 *expressions (str | Expression): the SQL code strings to parse. 1933 If a `From` instance is passed, this is used as-is. 1934 If another `Expression` instance is passed, it will be wrapped in a `From`. 1935 append (bool): if `True`, add to any existing expressions. 1936 Otherwise, this flattens all the `From` expression into a single expression. 1937 dialect (str): the dialect used to parse the input expression. 1938 copy (bool): if `False`, modify this expression instance in-place. 1939 opts (kwargs): other options to use to parse the input expressions. 1940 1941 Returns: 1942 Select: the modified expression. 1943 """ 1944 return _apply_child_list_builder( 1945 *expressions, 1946 instance=self, 1947 arg="from", 1948 append=append, 1949 copy=copy, 1950 prefix="FROM", 1951 into=From, 1952 dialect=dialect, 1953 **opts, 1954 ) 1955 1956 def group_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 1957 """ 1958 Set the GROUP BY expression. 1959 1960 Example: 1961 >>> Select().from_("tbl").select("x", "COUNT(1)").group_by("x").sql() 1962 'SELECT x, COUNT(1) FROM tbl GROUP BY x' 1963 1964 Args: 1965 *expressions (str | Expression): the SQL code strings to parse. 1966 If a `Group` instance is passed, this is used as-is. 1967 If another `Expression` instance is passed, it will be wrapped in a `Group`. 1968 If nothing is passed in then a group by is not applied to the expression 1969 append (bool): if `True`, add to any existing expressions. 1970 Otherwise, this flattens all the `Group` expression into a single expression. 1971 dialect (str): the dialect used to parse the input expression. 1972 copy (bool): if `False`, modify this expression instance in-place. 1973 opts (kwargs): other options to use to parse the input expressions. 1974 1975 Returns: 1976 Select: the modified expression. 1977 """ 1978 if not expressions: 1979 return self if not copy else self.copy() 1980 return _apply_child_list_builder( 1981 *expressions, 1982 instance=self, 1983 arg="group", 1984 append=append, 1985 copy=copy, 1986 prefix="GROUP BY", 1987 into=Group, 1988 dialect=dialect, 1989 **opts, 1990 ) 1991 1992 def order_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 1993 """ 1994 Set the ORDER BY expression. 1995 1996 Example: 1997 >>> Select().from_("tbl").select("x").order_by("x DESC").sql() 1998 'SELECT x FROM tbl ORDER BY x DESC' 1999 2000 Args: 2001 *expressions (str | Expression): the SQL code strings to parse. 2002 If a `Group` instance is passed, this is used as-is. 2003 If another `Expression` instance is passed, it will be wrapped in a `Order`. 2004 append (bool): if `True`, add to any existing expressions. 2005 Otherwise, this flattens all the `Order` expression into a single expression. 2006 dialect (str): the dialect used to parse the input expression. 2007 copy (bool): if `False`, modify this expression instance in-place. 2008 opts (kwargs): other options to use to parse the input expressions. 2009 2010 Returns: 2011 Select: the modified expression. 2012 """ 2013 return _apply_child_list_builder( 2014 *expressions, 2015 instance=self, 2016 arg="order", 2017 append=append, 2018 copy=copy, 2019 prefix="ORDER BY", 2020 into=Order, 2021 dialect=dialect, 2022 **opts, 2023 ) 2024 2025 def sort_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 2026 """ 2027 Set the SORT BY expression. 2028 2029 Example: 2030 >>> Select().from_("tbl").select("x").sort_by("x DESC").sql() 2031 'SELECT x FROM tbl SORT BY x DESC' 2032 2033 Args: 2034 *expressions (str | Expression): the SQL code strings to parse. 2035 If a `Group` instance is passed, this is used as-is. 2036 If another `Expression` instance is passed, it will be wrapped in a `SORT`. 2037 append (bool): if `True`, add to any existing expressions. 2038 Otherwise, this flattens all the `Order` expression into a single expression. 2039 dialect (str): the dialect used to parse the input expression. 2040 copy (bool): if `False`, modify this expression instance in-place. 2041 opts (kwargs): other options to use to parse the input expressions. 2042 2043 Returns: 2044 Select: the modified expression. 2045 """ 2046 return _apply_child_list_builder( 2047 *expressions, 2048 instance=self, 2049 arg="sort", 2050 append=append, 2051 copy=copy, 2052 prefix="SORT BY", 2053 into=Sort, 2054 dialect=dialect, 2055 **opts, 2056 ) 2057 2058 def cluster_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 2059 """ 2060 Set the CLUSTER BY expression. 2061 2062 Example: 2063 >>> Select().from_("tbl").select("x").cluster_by("x DESC").sql() 2064 'SELECT x FROM tbl CLUSTER BY x DESC' 2065 2066 Args: 2067 *expressions (str | Expression): the SQL code strings to parse. 2068 If a `Group` instance is passed, this is used as-is. 2069 If another `Expression` instance is passed, it will be wrapped in a `Cluster`. 2070 append (bool): if `True`, add to any existing expressions. 2071 Otherwise, this flattens all the `Order` expression into a single expression. 2072 dialect (str): the dialect used to parse the input expression. 2073 copy (bool): if `False`, modify this expression instance in-place. 2074 opts (kwargs): other options to use to parse the input expressions. 2075 2076 Returns: 2077 Select: the modified expression. 2078 """ 2079 return _apply_child_list_builder( 2080 *expressions, 2081 instance=self, 2082 arg="cluster", 2083 append=append, 2084 copy=copy, 2085 prefix="CLUSTER BY", 2086 into=Cluster, 2087 dialect=dialect, 2088 **opts, 2089 ) 2090 2091 def limit(self, expression, dialect=None, copy=True, **opts) -> Select: 2092 """ 2093 Set the LIMIT expression. 2094 2095 Example: 2096 >>> Select().from_("tbl").select("x").limit(10).sql() 2097 'SELECT x FROM tbl LIMIT 10' 2098 2099 Args: 2100 expression (str | int | Expression): the SQL code string to parse. 2101 This can also be an integer. 2102 If a `Limit` instance is passed, this is used as-is. 2103 If another `Expression` instance is passed, it will be wrapped in a `Limit`. 2104 dialect (str): the dialect used to parse the input expression. 2105 copy (bool): if `False`, modify this expression instance in-place. 2106 opts (kwargs): other options to use to parse the input expressions. 2107 2108 Returns: 2109 Select: the modified expression. 2110 """ 2111 return _apply_builder( 2112 expression=expression, 2113 instance=self, 2114 arg="limit", 2115 into=Limit, 2116 prefix="LIMIT", 2117 dialect=dialect, 2118 copy=copy, 2119 **opts, 2120 ) 2121 2122 def offset(self, expression, dialect=None, copy=True, **opts) -> Select: 2123 """ 2124 Set the OFFSET expression. 2125 2126 Example: 2127 >>> Select().from_("tbl").select("x").offset(10).sql() 2128 'SELECT x FROM tbl OFFSET 10' 2129 2130 Args: 2131 expression (str | int | Expression): the SQL code string to parse. 2132 This can also be an integer. 2133 If a `Offset` instance is passed, this is used as-is. 2134 If another `Expression` instance is passed, it will be wrapped in a `Offset`. 2135 dialect (str): the dialect used to parse the input expression. 2136 copy (bool): if `False`, modify this expression instance in-place. 2137 opts (kwargs): other options to use to parse the input expressions. 2138 2139 Returns: 2140 Select: the modified expression. 2141 """ 2142 return _apply_builder( 2143 expression=expression, 2144 instance=self, 2145 arg="offset", 2146 into=Offset, 2147 prefix="OFFSET", 2148 dialect=dialect, 2149 copy=copy, 2150 **opts, 2151 ) 2152 2153 def select( 2154 self, 2155 *expressions: str | Expression, 2156 append: bool = True, 2157 dialect: DialectType = None, 2158 copy: bool = True, 2159 **opts, 2160 ) -> Select: 2161 """ 2162 Append to or set the SELECT expressions. 2163 2164 Example: 2165 >>> Select().select("x", "y").sql() 2166 'SELECT x, y' 2167 2168 Args: 2169 *expressions: the SQL code strings to parse. 2170 If an `Expression` instance is passed, it will be used as-is. 2171 append: if `True`, add to any existing expressions. 2172 Otherwise, this resets the expressions. 2173 dialect: the dialect used to parse the input expressions. 2174 copy: if `False`, modify this expression instance in-place. 2175 opts: other options to use to parse the input expressions. 2176 2177 Returns: 2178 Select: the modified expression. 2179 """ 2180 return _apply_list_builder( 2181 *expressions, 2182 instance=self, 2183 arg="expressions", 2184 append=append, 2185 dialect=dialect, 2186 copy=copy, 2187 **opts, 2188 ) 2189 2190 def lateral(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 2191 """ 2192 Append to or set the LATERAL expressions. 2193 2194 Example: 2195 >>> Select().select("x").lateral("OUTER explode(y) tbl2 AS z").from_("tbl").sql() 2196 'SELECT x FROM tbl LATERAL VIEW OUTER EXPLODE(y) tbl2 AS z' 2197 2198 Args: 2199 *expressions (str | Expression): the SQL code strings to parse. 2200 If an `Expression` instance is passed, it will be used as-is. 2201 append (bool): if `True`, add to any existing expressions. 2202 Otherwise, this resets the expressions. 2203 dialect (str): the dialect used to parse the input expressions. 2204 copy (bool): if `False`, modify this expression instance in-place. 2205 opts (kwargs): other options to use to parse the input expressions. 2206 2207 Returns: 2208 Select: the modified expression. 2209 """ 2210 return _apply_list_builder( 2211 *expressions, 2212 instance=self, 2213 arg="laterals", 2214 append=append, 2215 into=Lateral, 2216 prefix="LATERAL VIEW", 2217 dialect=dialect, 2218 copy=copy, 2219 **opts, 2220 ) 2221 2222 def join( 2223 self, 2224 expression, 2225 on=None, 2226 using=None, 2227 append=True, 2228 join_type=None, 2229 join_alias=None, 2230 dialect=None, 2231 copy=True, 2232 **opts, 2233 ) -> Select: 2234 """ 2235 Append to or set the JOIN expressions. 2236 2237 Example: 2238 >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y").sql() 2239 'SELECT * FROM tbl JOIN tbl2 ON tbl1.y = tbl2.y' 2240 2241 >>> Select().select("1").from_("a").join("b", using=["x", "y", "z"]).sql() 2242 'SELECT 1 FROM a JOIN b USING (x, y, z)' 2243 2244 Use `join_type` to change the type of join: 2245 2246 >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y", join_type="left outer").sql() 2247 'SELECT * FROM tbl LEFT OUTER JOIN tbl2 ON tbl1.y = tbl2.y' 2248 2249 Args: 2250 expression (str | Expression): the SQL code string to parse. 2251 If an `Expression` instance is passed, it will be used as-is. 2252 on (str | Expression): optionally specify the join "on" criteria as a SQL string. 2253 If an `Expression` instance is passed, it will be used as-is. 2254 using (str | Expression): optionally specify the join "using" criteria as a SQL string. 2255 If an `Expression` instance is passed, it will be used as-is. 2256 append (bool): if `True`, add to any existing expressions. 2257 Otherwise, this resets the expressions. 2258 join_type (str): If set, alter the parsed join type 2259 dialect (str): the dialect used to parse the input expressions. 2260 copy (bool): if `False`, modify this expression instance in-place. 2261 opts (kwargs): other options to use to parse the input expressions. 2262 2263 Returns: 2264 Select: the modified expression. 2265 """ 2266 parse_args = {"dialect": dialect, **opts} 2267 2268 try: 2269 expression = maybe_parse(expression, into=Join, prefix="JOIN", **parse_args) 2270 except ParseError: 2271 expression = maybe_parse(expression, into=(Join, Expression), **parse_args) 2272 2273 join = expression if isinstance(expression, Join) else Join(this=expression) 2274 2275 if isinstance(join.this, Select): 2276 join.this.replace(join.this.subquery()) 2277 2278 if join_type: 2279 natural: t.Optional[Token] 2280 side: t.Optional[Token] 2281 kind: t.Optional[Token] 2282 2283 natural, side, kind = maybe_parse(join_type, into="JOIN_TYPE", **parse_args) # type: ignore 2284 2285 if natural: 2286 join.set("natural", True) 2287 if side: 2288 join.set("side", side.text) 2289 if kind: 2290 join.set("kind", kind.text) 2291 2292 if on: 2293 on = and_(*ensure_collection(on), dialect=dialect, **opts) 2294 join.set("on", on) 2295 2296 if using: 2297 join = _apply_list_builder( 2298 *ensure_collection(using), 2299 instance=join, 2300 arg="using", 2301 append=append, 2302 copy=copy, 2303 **opts, 2304 ) 2305 2306 if join_alias: 2307 join.set("this", alias_(join.this, join_alias, table=True)) 2308 return _apply_list_builder( 2309 join, 2310 instance=self, 2311 arg="joins", 2312 append=append, 2313 copy=copy, 2314 **opts, 2315 ) 2316 2317 def where(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 2318 """ 2319 Append to or set the WHERE expressions. 2320 2321 Example: 2322 >>> Select().select("x").from_("tbl").where("x = 'a' OR x < 'b'").sql() 2323 "SELECT x FROM tbl WHERE x = 'a' OR x < 'b'" 2324 2325 Args: 2326 *expressions (str | Expression): the SQL code strings to parse. 2327 If an `Expression` instance is passed, it will be used as-is. 2328 Multiple expressions are combined with an AND operator. 2329 append (bool): if `True`, AND the new expressions to any existing expression. 2330 Otherwise, this resets the expression. 2331 dialect (str): the dialect used to parse the input expressions. 2332 copy (bool): if `False`, modify this expression instance in-place. 2333 opts (kwargs): other options to use to parse the input expressions. 2334 2335 Returns: 2336 Select: the modified expression. 2337 """ 2338 return _apply_conjunction_builder( 2339 *expressions, 2340 instance=self, 2341 arg="where", 2342 append=append, 2343 into=Where, 2344 dialect=dialect, 2345 copy=copy, 2346 **opts, 2347 ) 2348 2349 def having(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 2350 """ 2351 Append to or set the HAVING expressions. 2352 2353 Example: 2354 >>> Select().select("x", "COUNT(y)").from_("tbl").group_by("x").having("COUNT(y) > 3").sql() 2355 'SELECT x, COUNT(y) FROM tbl GROUP BY x HAVING COUNT(y) > 3' 2356 2357 Args: 2358 *expressions (str | Expression): the SQL code strings to parse. 2359 If an `Expression` instance is passed, it will be used as-is. 2360 Multiple expressions are combined with an AND operator. 2361 append (bool): if `True`, AND the new expressions to any existing expression. 2362 Otherwise, this resets the expression. 2363 dialect (str): the dialect used to parse the input expressions. 2364 copy (bool): if `False`, modify this expression instance in-place. 2365 opts (kwargs): other options to use to parse the input expressions. 2366 2367 Returns: 2368 Select: the modified expression. 2369 """ 2370 return _apply_conjunction_builder( 2371 *expressions, 2372 instance=self, 2373 arg="having", 2374 append=append, 2375 into=Having, 2376 dialect=dialect, 2377 copy=copy, 2378 **opts, 2379 ) 2380 2381 def window(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 2382 return _apply_list_builder( 2383 *expressions, 2384 instance=self, 2385 arg="windows", 2386 append=append, 2387 into=Window, 2388 dialect=dialect, 2389 copy=copy, 2390 **opts, 2391 ) 2392 2393 def distinct(self, distinct=True, copy=True) -> Select: 2394 """ 2395 Set the OFFSET expression. 2396 2397 Example: 2398 >>> Select().from_("tbl").select("x").distinct().sql() 2399 'SELECT DISTINCT x FROM tbl' 2400 2401 Args: 2402 distinct (bool): whether the Select should be distinct 2403 copy (bool): if `False`, modify this expression instance in-place. 2404 2405 Returns: 2406 Select: the modified expression. 2407 """ 2408 instance = _maybe_copy(self, copy) 2409 instance.set("distinct", Distinct() if distinct else None) 2410 return instance 2411 2412 def ctas(self, table, properties=None, dialect=None, copy=True, **opts) -> Create: 2413 """ 2414 Convert this expression to a CREATE TABLE AS statement. 2415 2416 Example: 2417 >>> Select().select("*").from_("tbl").ctas("x").sql() 2418 'CREATE TABLE x AS SELECT * FROM tbl' 2419 2420 Args: 2421 table (str | Expression): the SQL code string to parse as the table name. 2422 If another `Expression` instance is passed, it will be used as-is. 2423 properties (dict): an optional mapping of table properties 2424 dialect (str): the dialect used to parse the input table. 2425 copy (bool): if `False`, modify this expression instance in-place. 2426 opts (kwargs): other options to use to parse the input table. 2427 2428 Returns: 2429 Create: the CREATE TABLE AS expression 2430 """ 2431 instance = _maybe_copy(self, copy) 2432 table_expression = maybe_parse( 2433 table, 2434 into=Table, 2435 dialect=dialect, 2436 **opts, 2437 ) 2438 properties_expression = None 2439 if properties: 2440 properties_expression = Properties.from_dict(properties) 2441 2442 return Create( 2443 this=table_expression, 2444 kind="table", 2445 expression=instance, 2446 properties=properties_expression, 2447 ) 2448 2449 def lock(self, update: bool = True, copy: bool = True) -> Select: 2450 """ 2451 Set the locking read mode for this expression. 2452 2453 Examples: 2454 >>> Select().select("x").from_("tbl").where("x = 'a'").lock().sql("mysql") 2455 "SELECT x FROM tbl WHERE x = 'a' FOR UPDATE" 2456 2457 >>> Select().select("x").from_("tbl").where("x = 'a'").lock(update=False).sql("mysql") 2458 "SELECT x FROM tbl WHERE x = 'a' FOR SHARE" 2459 2460 Args: 2461 update: if `True`, the locking type will be `FOR UPDATE`, else it will be `FOR SHARE`. 2462 copy: if `False`, modify this expression instance in-place. 2463 2464 Returns: 2465 The modified expression. 2466 """ 2467 2468 inst = _maybe_copy(self, copy) 2469 inst.set("lock", Lock(update=update)) 2470 2471 return inst 2472 2473 @property 2474 def named_selects(self) -> t.List[str]: 2475 return [e.output_name for e in self.expressions if e.alias_or_name] 2476 2477 @property 2478 def is_star(self) -> bool: 2479 return any(expression.is_star for expression in self.expressions) 2480 2481 @property 2482 def selects(self) -> t.List[Expression]: 2483 return self.expressions
def
from_( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
1923 def from_(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 1924 """ 1925 Set the FROM expression. 1926 1927 Example: 1928 >>> Select().from_("tbl").select("x").sql() 1929 'SELECT x FROM tbl' 1930 1931 Args: 1932 *expressions (str | Expression): the SQL code strings to parse. 1933 If a `From` instance is passed, this is used as-is. 1934 If another `Expression` instance is passed, it will be wrapped in a `From`. 1935 append (bool): if `True`, add to any existing expressions. 1936 Otherwise, this flattens all the `From` expression into a single expression. 1937 dialect (str): the dialect used to parse the input expression. 1938 copy (bool): if `False`, modify this expression instance in-place. 1939 opts (kwargs): other options to use to parse the input expressions. 1940 1941 Returns: 1942 Select: the modified expression. 1943 """ 1944 return _apply_child_list_builder( 1945 *expressions, 1946 instance=self, 1947 arg="from", 1948 append=append, 1949 copy=copy, 1950 prefix="FROM", 1951 into=From, 1952 dialect=dialect, 1953 **opts, 1954 )
Set the FROM expression.
Example:
>>> Select().from_("tbl").select("x").sql() 'SELECT x FROM tbl'
Arguments:
- *expressions (str | Expression): the SQL code strings to parse.
If a
Frominstance is passed, this is used as-is. If anotherExpressioninstance is passed, it will be wrapped in aFrom. - append (bool): if
True, add to any existing expressions. Otherwise, this flattens all theFromexpression into a single expression. - dialect (str): the dialect used to parse the input expression.
- copy (bool): if
False, modify this expression instance in-place. - opts (kwargs): other options to use to parse the input expressions.
Returns:
Select: the modified expression.
def
group_by( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
1956 def group_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 1957 """ 1958 Set the GROUP BY expression. 1959 1960 Example: 1961 >>> Select().from_("tbl").select("x", "COUNT(1)").group_by("x").sql() 1962 'SELECT x, COUNT(1) FROM tbl GROUP BY x' 1963 1964 Args: 1965 *expressions (str | Expression): the SQL code strings to parse. 1966 If a `Group` instance is passed, this is used as-is. 1967 If another `Expression` instance is passed, it will be wrapped in a `Group`. 1968 If nothing is passed in then a group by is not applied to the expression 1969 append (bool): if `True`, add to any existing expressions. 1970 Otherwise, this flattens all the `Group` expression into a single expression. 1971 dialect (str): the dialect used to parse the input expression. 1972 copy (bool): if `False`, modify this expression instance in-place. 1973 opts (kwargs): other options to use to parse the input expressions. 1974 1975 Returns: 1976 Select: the modified expression. 1977 """ 1978 if not expressions: 1979 return self if not copy else self.copy() 1980 return _apply_child_list_builder( 1981 *expressions, 1982 instance=self, 1983 arg="group", 1984 append=append, 1985 copy=copy, 1986 prefix="GROUP BY", 1987 into=Group, 1988 dialect=dialect, 1989 **opts, 1990 )
Set the GROUP BY expression.
Example:
>>> Select().from_("tbl").select("x", "COUNT(1)").group_by("x").sql() 'SELECT x, COUNT(1) FROM tbl GROUP BY x'
Arguments:
- *expressions (str | Expression): the SQL code strings to parse.
If a
Groupinstance is passed, this is used as-is. If anotherExpressioninstance is passed, it will be wrapped in aGroup. If nothing is passed in then a group by is not applied to the expression - append (bool): if
True, add to any existing expressions. Otherwise, this flattens all theGroupexpression into a single expression. - dialect (str): the dialect used to parse the input expression.
- copy (bool): if
False, modify this expression instance in-place. - opts (kwargs): other options to use to parse the input expressions.
Returns:
Select: the modified expression.
def
order_by( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
1992 def order_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 1993 """ 1994 Set the ORDER BY expression. 1995 1996 Example: 1997 >>> Select().from_("tbl").select("x").order_by("x DESC").sql() 1998 'SELECT x FROM tbl ORDER BY x DESC' 1999 2000 Args: 2001 *expressions (str | Expression): the SQL code strings to parse. 2002 If a `Group` instance is passed, this is used as-is. 2003 If another `Expression` instance is passed, it will be wrapped in a `Order`. 2004 append (bool): if `True`, add to any existing expressions. 2005 Otherwise, this flattens all the `Order` expression into a single expression. 2006 dialect (str): the dialect used to parse the input expression. 2007 copy (bool): if `False`, modify this expression instance in-place. 2008 opts (kwargs): other options to use to parse the input expressions. 2009 2010 Returns: 2011 Select: the modified expression. 2012 """ 2013 return _apply_child_list_builder( 2014 *expressions, 2015 instance=self, 2016 arg="order", 2017 append=append, 2018 copy=copy, 2019 prefix="ORDER BY", 2020 into=Order, 2021 dialect=dialect, 2022 **opts, 2023 )
Set the ORDER BY expression.
Example:
>>> Select().from_("tbl").select("x").order_by("x DESC").sql() 'SELECT x FROM tbl ORDER BY x DESC'
Arguments:
- *expressions (str | Expression): the SQL code strings to parse.
If a
Groupinstance is passed, this is used as-is. If anotherExpressioninstance is passed, it will be wrapped in aOrder. - append (bool): if
True, add to any existing expressions. Otherwise, this flattens all theOrderexpression into a single expression. - dialect (str): the dialect used to parse the input expression.
- copy (bool): if
False, modify this expression instance in-place. - opts (kwargs): other options to use to parse the input expressions.
Returns:
Select: the modified expression.
def
sort_by( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
2025 def sort_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 2026 """ 2027 Set the SORT BY expression. 2028 2029 Example: 2030 >>> Select().from_("tbl").select("x").sort_by("x DESC").sql() 2031 'SELECT x FROM tbl SORT BY x DESC' 2032 2033 Args: 2034 *expressions (str | Expression): the SQL code strings to parse. 2035 If a `Group` instance is passed, this is used as-is. 2036 If another `Expression` instance is passed, it will be wrapped in a `SORT`. 2037 append (bool): if `True`, add to any existing expressions. 2038 Otherwise, this flattens all the `Order` expression into a single expression. 2039 dialect (str): the dialect used to parse the input expression. 2040 copy (bool): if `False`, modify this expression instance in-place. 2041 opts (kwargs): other options to use to parse the input expressions. 2042 2043 Returns: 2044 Select: the modified expression. 2045 """ 2046 return _apply_child_list_builder( 2047 *expressions, 2048 instance=self, 2049 arg="sort", 2050 append=append, 2051 copy=copy, 2052 prefix="SORT BY", 2053 into=Sort, 2054 dialect=dialect, 2055 **opts, 2056 )
Set the SORT BY expression.
Example:
>>> Select().from_("tbl").select("x").sort_by("x DESC").sql() 'SELECT x FROM tbl SORT BY x DESC'
Arguments:
- *expressions (str | Expression): the SQL code strings to parse.
If a
Groupinstance is passed, this is used as-is. If anotherExpressioninstance is passed, it will be wrapped in aSORT. - append (bool): if
True, add to any existing expressions. Otherwise, this flattens all theOrderexpression into a single expression. - dialect (str): the dialect used to parse the input expression.
- copy (bool): if
False, modify this expression instance in-place. - opts (kwargs): other options to use to parse the input expressions.
Returns:
Select: the modified expression.
def
cluster_by( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
2058 def cluster_by(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 2059 """ 2060 Set the CLUSTER BY expression. 2061 2062 Example: 2063 >>> Select().from_("tbl").select("x").cluster_by("x DESC").sql() 2064 'SELECT x FROM tbl CLUSTER BY x DESC' 2065 2066 Args: 2067 *expressions (str | Expression): the SQL code strings to parse. 2068 If a `Group` instance is passed, this is used as-is. 2069 If another `Expression` instance is passed, it will be wrapped in a `Cluster`. 2070 append (bool): if `True`, add to any existing expressions. 2071 Otherwise, this flattens all the `Order` expression into a single expression. 2072 dialect (str): the dialect used to parse the input expression. 2073 copy (bool): if `False`, modify this expression instance in-place. 2074 opts (kwargs): other options to use to parse the input expressions. 2075 2076 Returns: 2077 Select: the modified expression. 2078 """ 2079 return _apply_child_list_builder( 2080 *expressions, 2081 instance=self, 2082 arg="cluster", 2083 append=append, 2084 copy=copy, 2085 prefix="CLUSTER BY", 2086 into=Cluster, 2087 dialect=dialect, 2088 **opts, 2089 )
Set the CLUSTER BY expression.
Example:
>>> Select().from_("tbl").select("x").cluster_by("x DESC").sql() 'SELECT x FROM tbl CLUSTER BY x DESC'
Arguments:
- *expressions (str | Expression): the SQL code strings to parse.
If a
Groupinstance is passed, this is used as-is. If anotherExpressioninstance is passed, it will be wrapped in aCluster. - append (bool): if
True, add to any existing expressions. Otherwise, this flattens all theOrderexpression into a single expression. - dialect (str): the dialect used to parse the input expression.
- copy (bool): if
False, modify this expression instance in-place. - opts (kwargs): other options to use to parse the input expressions.
Returns:
Select: the modified expression.
2091 def limit(self, expression, dialect=None, copy=True, **opts) -> Select: 2092 """ 2093 Set the LIMIT expression. 2094 2095 Example: 2096 >>> Select().from_("tbl").select("x").limit(10).sql() 2097 'SELECT x FROM tbl LIMIT 10' 2098 2099 Args: 2100 expression (str | int | Expression): the SQL code string to parse. 2101 This can also be an integer. 2102 If a `Limit` instance is passed, this is used as-is. 2103 If another `Expression` instance is passed, it will be wrapped in a `Limit`. 2104 dialect (str): the dialect used to parse the input expression. 2105 copy (bool): if `False`, modify this expression instance in-place. 2106 opts (kwargs): other options to use to parse the input expressions. 2107 2108 Returns: 2109 Select: the modified expression. 2110 """ 2111 return _apply_builder( 2112 expression=expression, 2113 instance=self, 2114 arg="limit", 2115 into=Limit, 2116 prefix="LIMIT", 2117 dialect=dialect, 2118 copy=copy, 2119 **opts, 2120 )
Set the LIMIT expression.
Example:
>>> Select().from_("tbl").select("x").limit(10).sql() 'SELECT x FROM tbl LIMIT 10'
Arguments:
- expression (str | int | Expression): the SQL code string to parse.
This can also be an integer.
If a
Limitinstance is passed, this is used as-is. If anotherExpressioninstance is passed, it will be wrapped in aLimit. - dialect (str): the dialect used to parse the input expression.
- copy (bool): if
False, modify this expression instance in-place. - opts (kwargs): other options to use to parse the input expressions.
Returns:
Select: the modified expression.
2122 def offset(self, expression, dialect=None, copy=True, **opts) -> Select: 2123 """ 2124 Set the OFFSET expression. 2125 2126 Example: 2127 >>> Select().from_("tbl").select("x").offset(10).sql() 2128 'SELECT x FROM tbl OFFSET 10' 2129 2130 Args: 2131 expression (str | int | Expression): the SQL code string to parse. 2132 This can also be an integer. 2133 If a `Offset` instance is passed, this is used as-is. 2134 If another `Expression` instance is passed, it will be wrapped in a `Offset`. 2135 dialect (str): the dialect used to parse the input expression. 2136 copy (bool): if `False`, modify this expression instance in-place. 2137 opts (kwargs): other options to use to parse the input expressions. 2138 2139 Returns: 2140 Select: the modified expression. 2141 """ 2142 return _apply_builder( 2143 expression=expression, 2144 instance=self, 2145 arg="offset", 2146 into=Offset, 2147 prefix="OFFSET", 2148 dialect=dialect, 2149 copy=copy, 2150 **opts, 2151 )
Set the OFFSET expression.
Example:
>>> Select().from_("tbl").select("x").offset(10).sql() 'SELECT x FROM tbl OFFSET 10'
Arguments:
- expression (str | int | Expression): the SQL code string to parse.
This can also be an integer.
If a
Offsetinstance is passed, this is used as-is. If anotherExpressioninstance is passed, it will be wrapped in aOffset. - dialect (str): the dialect used to parse the input expression.
- copy (bool): if
False, modify this expression instance in-place. - opts (kwargs): other options to use to parse the input expressions.
Returns:
Select: the modified expression.
def
select( self, *expressions: str | sqlglot.expressions.Expression, append: bool = True, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, copy: bool = True, **opts) -> sqlglot.expressions.Select:
2153 def select( 2154 self, 2155 *expressions: str | Expression, 2156 append: bool = True, 2157 dialect: DialectType = None, 2158 copy: bool = True, 2159 **opts, 2160 ) -> Select: 2161 """ 2162 Append to or set the SELECT expressions. 2163 2164 Example: 2165 >>> Select().select("x", "y").sql() 2166 'SELECT x, y' 2167 2168 Args: 2169 *expressions: the SQL code strings to parse. 2170 If an `Expression` instance is passed, it will be used as-is. 2171 append: if `True`, add to any existing expressions. 2172 Otherwise, this resets the expressions. 2173 dialect: the dialect used to parse the input expressions. 2174 copy: if `False`, modify this expression instance in-place. 2175 opts: other options to use to parse the input expressions. 2176 2177 Returns: 2178 Select: the modified expression. 2179 """ 2180 return _apply_list_builder( 2181 *expressions, 2182 instance=self, 2183 arg="expressions", 2184 append=append, 2185 dialect=dialect, 2186 copy=copy, 2187 **opts, 2188 )
Append to or set the SELECT expressions.
Example:
>>> Select().select("x", "y").sql() 'SELECT x, y'
Arguments:
- *expressions: the SQL code strings to parse.
If an
Expressioninstance is passed, it will be used as-is. - append: if
True, add to any existing expressions. Otherwise, this resets the expressions. - dialect: the dialect used to parse the input expressions.
- copy: if
False, modify this expression instance in-place. - opts: other options to use to parse the input expressions.
Returns:
Select: the modified expression.
def
lateral( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
2190 def lateral(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 2191 """ 2192 Append to or set the LATERAL expressions. 2193 2194 Example: 2195 >>> Select().select("x").lateral("OUTER explode(y) tbl2 AS z").from_("tbl").sql() 2196 'SELECT x FROM tbl LATERAL VIEW OUTER EXPLODE(y) tbl2 AS z' 2197 2198 Args: 2199 *expressions (str | Expression): the SQL code strings to parse. 2200 If an `Expression` instance is passed, it will be used as-is. 2201 append (bool): if `True`, add to any existing expressions. 2202 Otherwise, this resets the expressions. 2203 dialect (str): the dialect used to parse the input expressions. 2204 copy (bool): if `False`, modify this expression instance in-place. 2205 opts (kwargs): other options to use to parse the input expressions. 2206 2207 Returns: 2208 Select: the modified expression. 2209 """ 2210 return _apply_list_builder( 2211 *expressions, 2212 instance=self, 2213 arg="laterals", 2214 append=append, 2215 into=Lateral, 2216 prefix="LATERAL VIEW", 2217 dialect=dialect, 2218 copy=copy, 2219 **opts, 2220 )
Append to or set the LATERAL expressions.
Example:
>>> Select().select("x").lateral("OUTER explode(y) tbl2 AS z").from_("tbl").sql() 'SELECT x FROM tbl LATERAL VIEW OUTER EXPLODE(y) tbl2 AS z'
Arguments:
- *expressions (str | Expression): the SQL code strings to parse.
If an
Expressioninstance is passed, it will be used as-is. - append (bool): if
True, add to any existing expressions. Otherwise, this resets the expressions. - dialect (str): the dialect used to parse the input expressions.
- copy (bool): if
False, modify this expression instance in-place. - opts (kwargs): other options to use to parse the input expressions.
Returns:
Select: the modified expression.
def
join( self, expression, on=None, using=None, append=True, join_type=None, join_alias=None, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
2222 def join( 2223 self, 2224 expression, 2225 on=None, 2226 using=None, 2227 append=True, 2228 join_type=None, 2229 join_alias=None, 2230 dialect=None, 2231 copy=True, 2232 **opts, 2233 ) -> Select: 2234 """ 2235 Append to or set the JOIN expressions. 2236 2237 Example: 2238 >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y").sql() 2239 'SELECT * FROM tbl JOIN tbl2 ON tbl1.y = tbl2.y' 2240 2241 >>> Select().select("1").from_("a").join("b", using=["x", "y", "z"]).sql() 2242 'SELECT 1 FROM a JOIN b USING (x, y, z)' 2243 2244 Use `join_type` to change the type of join: 2245 2246 >>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y", join_type="left outer").sql() 2247 'SELECT * FROM tbl LEFT OUTER JOIN tbl2 ON tbl1.y = tbl2.y' 2248 2249 Args: 2250 expression (str | Expression): the SQL code string to parse. 2251 If an `Expression` instance is passed, it will be used as-is. 2252 on (str | Expression): optionally specify the join "on" criteria as a SQL string. 2253 If an `Expression` instance is passed, it will be used as-is. 2254 using (str | Expression): optionally specify the join "using" criteria as a SQL string. 2255 If an `Expression` instance is passed, it will be used as-is. 2256 append (bool): if `True`, add to any existing expressions. 2257 Otherwise, this resets the expressions. 2258 join_type (str): If set, alter the parsed join type 2259 dialect (str): the dialect used to parse the input expressions. 2260 copy (bool): if `False`, modify this expression instance in-place. 2261 opts (kwargs): other options to use to parse the input expressions. 2262 2263 Returns: 2264 Select: the modified expression. 2265 """ 2266 parse_args = {"dialect": dialect, **opts} 2267 2268 try: 2269 expression = maybe_parse(expression, into=Join, prefix="JOIN", **parse_args) 2270 except ParseError: 2271 expression = maybe_parse(expression, into=(Join, Expression), **parse_args) 2272 2273 join = expression if isinstance(expression, Join) else Join(this=expression) 2274 2275 if isinstance(join.this, Select): 2276 join.this.replace(join.this.subquery()) 2277 2278 if join_type: 2279 natural: t.Optional[Token] 2280 side: t.Optional[Token] 2281 kind: t.Optional[Token] 2282 2283 natural, side, kind = maybe_parse(join_type, into="JOIN_TYPE", **parse_args) # type: ignore 2284 2285 if natural: 2286 join.set("natural", True) 2287 if side: 2288 join.set("side", side.text) 2289 if kind: 2290 join.set("kind", kind.text) 2291 2292 if on: 2293 on = and_(*ensure_collection(on), dialect=dialect, **opts) 2294 join.set("on", on) 2295 2296 if using: 2297 join = _apply_list_builder( 2298 *ensure_collection(using), 2299 instance=join, 2300 arg="using", 2301 append=append, 2302 copy=copy, 2303 **opts, 2304 ) 2305 2306 if join_alias: 2307 join.set("this", alias_(join.this, join_alias, table=True)) 2308 return _apply_list_builder( 2309 join, 2310 instance=self, 2311 arg="joins", 2312 append=append, 2313 copy=copy, 2314 **opts, 2315 )
Append to or set the JOIN expressions.
Example:
>>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y").sql() 'SELECT * FROM tbl JOIN tbl2 ON tbl1.y = tbl2.y'>>> Select().select("1").from_("a").join("b", using=["x", "y", "z"]).sql() 'SELECT 1 FROM a JOIN b USING (x, y, z)'Use
join_typeto change the type of join:>>> Select().select("*").from_("tbl").join("tbl2", on="tbl1.y = tbl2.y", join_type="left outer").sql() 'SELECT * FROM tbl LEFT OUTER JOIN tbl2 ON tbl1.y = tbl2.y'
Arguments:
- expression (str | Expression): the SQL code string to parse.
If an
Expressioninstance is passed, it will be used as-is. - on (str | Expression): optionally specify the join "on" criteria as a SQL string.
If an
Expressioninstance is passed, it will be used as-is. - using (str | Expression): optionally specify the join "using" criteria as a SQL string.
If an
Expressioninstance is passed, it will be used as-is. - append (bool): if
True, add to any existing expressions. Otherwise, this resets the expressions. - join_type (str): If set, alter the parsed join type
- dialect (str): the dialect used to parse the input expressions.
- copy (bool): if
False, modify this expression instance in-place. - opts (kwargs): other options to use to parse the input expressions.
Returns:
Select: the modified expression.
def
where( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
2317 def where(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 2318 """ 2319 Append to or set the WHERE expressions. 2320 2321 Example: 2322 >>> Select().select("x").from_("tbl").where("x = 'a' OR x < 'b'").sql() 2323 "SELECT x FROM tbl WHERE x = 'a' OR x < 'b'" 2324 2325 Args: 2326 *expressions (str | Expression): the SQL code strings to parse. 2327 If an `Expression` instance is passed, it will be used as-is. 2328 Multiple expressions are combined with an AND operator. 2329 append (bool): if `True`, AND the new expressions to any existing expression. 2330 Otherwise, this resets the expression. 2331 dialect (str): the dialect used to parse the input expressions. 2332 copy (bool): if `False`, modify this expression instance in-place. 2333 opts (kwargs): other options to use to parse the input expressions. 2334 2335 Returns: 2336 Select: the modified expression. 2337 """ 2338 return _apply_conjunction_builder( 2339 *expressions, 2340 instance=self, 2341 arg="where", 2342 append=append, 2343 into=Where, 2344 dialect=dialect, 2345 copy=copy, 2346 **opts, 2347 )
Append to or set the WHERE expressions.
Example:
>>> Select().select("x").from_("tbl").where("x = 'a' OR x < 'b'").sql() "SELECT x FROM tbl WHERE x = 'a' OR x < 'b'"
Arguments:
- *expressions (str | Expression): the SQL code strings to parse.
If an
Expressioninstance is passed, it will be used as-is. Multiple expressions are combined with an AND operator. - append (bool): if
True, AND the new expressions to any existing expression. Otherwise, this resets the expression. - dialect (str): the dialect used to parse the input expressions.
- copy (bool): if
False, modify this expression instance in-place. - opts (kwargs): other options to use to parse the input expressions.
Returns:
Select: the modified expression.
def
having( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
2349 def having(self, *expressions, append=True, dialect=None, copy=True, **opts) -> Select: 2350 """ 2351 Append to or set the HAVING expressions. 2352 2353 Example: 2354 >>> Select().select("x", "COUNT(y)").from_("tbl").group_by("x").having("COUNT(y) > 3").sql() 2355 'SELECT x, COUNT(y) FROM tbl GROUP BY x HAVING COUNT(y) > 3' 2356 2357 Args: 2358 *expressions (str | Expression): the SQL code strings to parse. 2359 If an `Expression` instance is passed, it will be used as-is. 2360 Multiple expressions are combined with an AND operator. 2361 append (bool): if `True`, AND the new expressions to any existing expression. 2362 Otherwise, this resets the expression. 2363 dialect (str): the dialect used to parse the input expressions. 2364 copy (bool): if `False`, modify this expression instance in-place. 2365 opts (kwargs): other options to use to parse the input expressions. 2366 2367 Returns: 2368 Select: the modified expression. 2369 """ 2370 return _apply_conjunction_builder( 2371 *expressions, 2372 instance=self, 2373 arg="having", 2374 append=append, 2375 into=Having, 2376 dialect=dialect, 2377 copy=copy, 2378 **opts, 2379 )
Append to or set the HAVING expressions.
Example:
>>> Select().select("x", "COUNT(y)").from_("tbl").group_by("x").having("COUNT(y) > 3").sql() 'SELECT x, COUNT(y) FROM tbl GROUP BY x HAVING COUNT(y) > 3'
Arguments:
- *expressions (str | Expression): the SQL code strings to parse.
If an
Expressioninstance is passed, it will be used as-is. Multiple expressions are combined with an AND operator. - append (bool): if
True, AND the new expressions to any existing expression. Otherwise, this resets the expression. - dialect (str): the dialect used to parse the input expressions.
- copy (bool): if
False, modify this expression instance in-place. - opts (kwargs): other options to use to parse the input expressions.
Returns:
Select: the modified expression.
def
window( self, *expressions, append=True, dialect=None, copy=True, **opts) -> sqlglot.expressions.Select:
2393 def distinct(self, distinct=True, copy=True) -> Select: 2394 """ 2395 Set the OFFSET expression. 2396 2397 Example: 2398 >>> Select().from_("tbl").select("x").distinct().sql() 2399 'SELECT DISTINCT x FROM tbl' 2400 2401 Args: 2402 distinct (bool): whether the Select should be distinct 2403 copy (bool): if `False`, modify this expression instance in-place. 2404 2405 Returns: 2406 Select: the modified expression. 2407 """ 2408 instance = _maybe_copy(self, copy) 2409 instance.set("distinct", Distinct() if distinct else None) 2410 return instance
Set the OFFSET expression.
Example:
>>> Select().from_("tbl").select("x").distinct().sql() 'SELECT DISTINCT x FROM tbl'
Arguments:
- distinct (bool): whether the Select should be distinct
- copy (bool): if
False, modify this expression instance in-place.
Returns:
Select: the modified expression.
def
ctas( self, table, properties=None, dialect=None, copy=True, **opts) -> sqlglot.expressions.Create:
2412 def ctas(self, table, properties=None, dialect=None, copy=True, **opts) -> Create: 2413 """ 2414 Convert this expression to a CREATE TABLE AS statement. 2415 2416 Example: 2417 >>> Select().select("*").from_("tbl").ctas("x").sql() 2418 'CREATE TABLE x AS SELECT * FROM tbl' 2419 2420 Args: 2421 table (str | Expression): the SQL code string to parse as the table name. 2422 If another `Expression` instance is passed, it will be used as-is. 2423 properties (dict): an optional mapping of table properties 2424 dialect (str): the dialect used to parse the input table. 2425 copy (bool): if `False`, modify this expression instance in-place. 2426 opts (kwargs): other options to use to parse the input table. 2427 2428 Returns: 2429 Create: the CREATE TABLE AS expression 2430 """ 2431 instance = _maybe_copy(self, copy) 2432 table_expression = maybe_parse( 2433 table, 2434 into=Table, 2435 dialect=dialect, 2436 **opts, 2437 ) 2438 properties_expression = None 2439 if properties: 2440 properties_expression = Properties.from_dict(properties) 2441 2442 return Create( 2443 this=table_expression, 2444 kind="table", 2445 expression=instance, 2446 properties=properties_expression, 2447 )
Convert this expression to a CREATE TABLE AS statement.
Example:
>>> Select().select("*").from_("tbl").ctas("x").sql() 'CREATE TABLE x AS SELECT * FROM tbl'
Arguments:
- table (str | Expression): the SQL code string to parse as the table name.
If another
Expressioninstance is passed, it will be used as-is. - properties (dict): an optional mapping of table properties
- dialect (str): the dialect used to parse the input table.
- copy (bool): if
False, modify this expression instance in-place. - opts (kwargs): other options to use to parse the input table.
Returns:
Create: the CREATE TABLE AS expression
2449 def lock(self, update: bool = True, copy: bool = True) -> Select: 2450 """ 2451 Set the locking read mode for this expression. 2452 2453 Examples: 2454 >>> Select().select("x").from_("tbl").where("x = 'a'").lock().sql("mysql") 2455 "SELECT x FROM tbl WHERE x = 'a' FOR UPDATE" 2456 2457 >>> Select().select("x").from_("tbl").where("x = 'a'").lock(update=False).sql("mysql") 2458 "SELECT x FROM tbl WHERE x = 'a' FOR SHARE" 2459 2460 Args: 2461 update: if `True`, the locking type will be `FOR UPDATE`, else it will be `FOR SHARE`. 2462 copy: if `False`, modify this expression instance in-place. 2463 2464 Returns: 2465 The modified expression. 2466 """ 2467 2468 inst = _maybe_copy(self, copy) 2469 inst.set("lock", Lock(update=update)) 2470 2471 return inst
Set the locking read mode for this expression.
Examples:
>>> Select().select("x").from_("tbl").where("x = 'a'").lock().sql("mysql") "SELECT x FROM tbl WHERE x = 'a' FOR UPDATE">>> Select().select("x").from_("tbl").where("x = 'a'").lock(update=False).sql("mysql") "SELECT x FROM tbl WHERE x = 'a' FOR SHARE"
Arguments:
- update: if
True, the locking type will beFOR UPDATE, else it will beFOR SHARE. - copy: if
False, modify this expression instance in-place.
Returns:
The modified expression.
Inherited Members
2486class Subquery(DerivedTable, Unionable): 2487 arg_types = { 2488 "this": True, 2489 "alias": False, 2490 "with": False, 2491 **QUERY_MODIFIERS, 2492 } 2493 2494 def unnest(self): 2495 """ 2496 Returns the first non subquery. 2497 """ 2498 expression = self 2499 while isinstance(expression, Subquery): 2500 expression = expression.this 2501 return expression 2502 2503 @property 2504 def is_star(self) -> bool: 2505 return self.this.is_star 2506 2507 @property 2508 def output_name(self): 2509 return self.alias
def
unnest(self):
2494 def unnest(self): 2495 """ 2496 Returns the first non subquery. 2497 """ 2498 expression = self 2499 while isinstance(expression, Subquery): 2500 expression = expression.this 2501 return expression
Returns the first non subquery.
output_name
Name of the output column if this expression is a selection.
If the Expression has no output name, an empty string is returned.
Example:
>>> from sqlglot import parse_one >>> parse_one("SELECT a").expressions[0].output_name 'a' >>> parse_one("SELECT b AS c").expressions[0].output_name 'c' >>> parse_one("SELECT 1 + 2").expressions[0].output_name ''
Inherited Members
2512class TableSample(Expression): 2513 arg_types = { 2514 "this": False, 2515 "method": False, 2516 "bucket_numerator": False, 2517 "bucket_denominator": False, 2518 "bucket_field": False, 2519 "percent": False, 2520 "rows": False, 2521 "size": False, 2522 "seed": False, 2523 }
Inherited Members
2526class Tag(Expression): 2527 """Tags are used for generating arbitrary sql like SELECT <span>x</span>.""" 2528 2529 arg_types = { 2530 "this": False, 2531 "prefix": False, 2532 "postfix": False, 2533 }
Tags are used for generating arbitrary sql like SELECT x.
Inherited Members
2536class Pivot(Expression): 2537 arg_types = { 2538 "this": False, 2539 "alias": False, 2540 "expressions": True, 2541 "field": True, 2542 "unpivot": True, 2543 }
Inherited Members
2546class Window(Expression): 2547 arg_types = { 2548 "this": True, 2549 "partition_by": False, 2550 "order": False, 2551 "spec": False, 2552 "alias": False, 2553 }
Inherited Members
2556class WindowSpec(Expression): 2557 arg_types = { 2558 "kind": False, 2559 "start": False, 2560 "start_side": False, 2561 "end": False, 2562 "end_side": False, 2563 }
Inherited Members
Inherited Members
2570class Star(Expression): 2571 arg_types = {"except": False, "replace": False} 2572 2573 @property 2574 def name(self) -> str: 2575 return "*" 2576 2577 @property 2578 def output_name(self): 2579 return self.name
output_name
Name of the output column if this expression is a selection.
If the Expression has no output name, an empty string is returned.
Example:
>>> from sqlglot import parse_one >>> parse_one("SELECT a").expressions[0].output_name 'a' >>> parse_one("SELECT b AS c").expressions[0].output_name 'c' >>> parse_one("SELECT 1 + 2").expressions[0].output_name ''
Inherited Members
Inherited Members
Inherited Members
2594class Null(Condition): 2595 arg_types: t.Dict[str, t.Any] = {} 2596 2597 @property 2598 def name(self) -> str: 2599 return "NULL"
Inherited Members
Inherited Members
2606class DataType(Expression): 2607 arg_types = { 2608 "this": True, 2609 "expressions": False, 2610 "nested": False, 2611 "values": False, 2612 "prefix": False, 2613 } 2614 2615 class Type(AutoName): 2616 CHAR = auto() 2617 NCHAR = auto() 2618 VARCHAR = auto() 2619 NVARCHAR = auto() 2620 TEXT = auto() 2621 MEDIUMTEXT = auto() 2622 LONGTEXT = auto() 2623 MEDIUMBLOB = auto() 2624 LONGBLOB = auto() 2625 BINARY = auto() 2626 VARBINARY = auto() 2627 INT = auto() 2628 TINYINT = auto() 2629 SMALLINT = auto() 2630 BIGINT = auto() 2631 FLOAT = auto() 2632 DOUBLE = auto() 2633 DECIMAL = auto() 2634 BOOLEAN = auto() 2635 JSON = auto() 2636 JSONB = auto() 2637 INTERVAL = auto() 2638 TIME = auto() 2639 TIMESTAMP = auto() 2640 TIMESTAMPTZ = auto() 2641 TIMESTAMPLTZ = auto() 2642 DATE = auto() 2643 DATETIME = auto() 2644 ARRAY = auto() 2645 MAP = auto() 2646 UUID = auto() 2647 GEOGRAPHY = auto() 2648 GEOMETRY = auto() 2649 STRUCT = auto() 2650 NULLABLE = auto() 2651 HLLSKETCH = auto() 2652 HSTORE = auto() 2653 SUPER = auto() 2654 SERIAL = auto() 2655 SMALLSERIAL = auto() 2656 BIGSERIAL = auto() 2657 XML = auto() 2658 UNIQUEIDENTIFIER = auto() 2659 MONEY = auto() 2660 SMALLMONEY = auto() 2661 ROWVERSION = auto() 2662 IMAGE = auto() 2663 VARIANT = auto() 2664 OBJECT = auto() 2665 INET = auto() 2666 NULL = auto() 2667 UNKNOWN = auto() # Sentinel value, useful for type annotation 2668 2669 TEXT_TYPES = { 2670 Type.CHAR, 2671 Type.NCHAR, 2672 Type.VARCHAR, 2673 Type.NVARCHAR, 2674 Type.TEXT, 2675 } 2676 2677 INTEGER_TYPES = { 2678 Type.INT, 2679 Type.TINYINT, 2680 Type.SMALLINT, 2681 Type.BIGINT, 2682 } 2683 2684 FLOAT_TYPES = { 2685 Type.FLOAT, 2686 Type.DOUBLE, 2687 } 2688 2689 NUMERIC_TYPES = {*INTEGER_TYPES, *FLOAT_TYPES} 2690 2691 TEMPORAL_TYPES = { 2692 Type.TIMESTAMP, 2693 Type.TIMESTAMPTZ, 2694 Type.TIMESTAMPLTZ, 2695 Type.DATE, 2696 Type.DATETIME, 2697 } 2698 2699 @classmethod 2700 def build( 2701 cls, dtype: str | DataType | DataType.Type, dialect: DialectType = None, **kwargs 2702 ) -> DataType: 2703 from sqlglot import parse_one 2704 2705 if isinstance(dtype, str): 2706 if dtype.upper() in cls.Type.__members__: 2707 data_type_exp: t.Optional[Expression] = DataType(this=DataType.Type[dtype.upper()]) 2708 else: 2709 data_type_exp = parse_one(dtype, read=dialect, into=DataType) 2710 if data_type_exp is None: 2711 raise ValueError(f"Unparsable data type value: {dtype}") 2712 elif isinstance(dtype, DataType.Type): 2713 data_type_exp = DataType(this=dtype) 2714 elif isinstance(dtype, DataType): 2715 return dtype 2716 else: 2717 raise ValueError(f"Invalid data type: {type(dtype)}. Expected str or DataType.Type") 2718 return DataType(**{**data_type_exp.args, **kwargs}) 2719 2720 def is_type(self, dtype: DataType.Type) -> bool: 2721 return self.this == dtype
@classmethod
def
build( cls, dtype: str | sqlglot.expressions.DataType | sqlglot.expressions.DataType.Type, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, **kwargs) -> sqlglot.expressions.DataType:
2699 @classmethod 2700 def build( 2701 cls, dtype: str | DataType | DataType.Type, dialect: DialectType = None, **kwargs 2702 ) -> DataType: 2703 from sqlglot import parse_one 2704 2705 if isinstance(dtype, str): 2706 if dtype.upper() in cls.Type.__members__: 2707 data_type_exp: t.Optional[Expression] = DataType(this=DataType.Type[dtype.upper()]) 2708 else: 2709 data_type_exp = parse_one(dtype, read=dialect, into=DataType) 2710 if data_type_exp is None: 2711 raise ValueError(f"Unparsable data type value: {dtype}") 2712 elif isinstance(dtype, DataType.Type): 2713 data_type_exp = DataType(this=dtype) 2714 elif isinstance(dtype, DataType): 2715 return dtype 2716 else: 2717 raise ValueError(f"Invalid data type: {type(dtype)}. Expected str or DataType.Type") 2718 return DataType(**{**data_type_exp.args, **kwargs})
Inherited Members
2615 class Type(AutoName): 2616 CHAR = auto() 2617 NCHAR = auto() 2618 VARCHAR = auto() 2619 NVARCHAR = auto() 2620 TEXT = auto() 2621 MEDIUMTEXT = auto() 2622 LONGTEXT = auto() 2623 MEDIUMBLOB = auto() 2624 LONGBLOB = auto() 2625 BINARY = auto() 2626 VARBINARY = auto() 2627 INT = auto() 2628 TINYINT = auto() 2629 SMALLINT = auto() 2630 BIGINT = auto() 2631 FLOAT = auto() 2632 DOUBLE = auto() 2633 DECIMAL = auto() 2634 BOOLEAN = auto() 2635 JSON = auto() 2636 JSONB = auto() 2637 INTERVAL = auto() 2638 TIME = auto() 2639 TIMESTAMP = auto() 2640 TIMESTAMPTZ = auto() 2641 TIMESTAMPLTZ = auto() 2642 DATE = auto() 2643 DATETIME = auto() 2644 ARRAY = auto() 2645 MAP = auto() 2646 UUID = auto() 2647 GEOGRAPHY = auto() 2648 GEOMETRY = auto() 2649 STRUCT = auto() 2650 NULLABLE = auto() 2651 HLLSKETCH = auto() 2652 HSTORE = auto() 2653 SUPER = auto() 2654 SERIAL = auto() 2655 SMALLSERIAL = auto() 2656 BIGSERIAL = auto() 2657 XML = auto() 2658 UNIQUEIDENTIFIER = auto() 2659 MONEY = auto() 2660 SMALLMONEY = auto() 2661 ROWVERSION = auto() 2662 IMAGE = auto() 2663 VARIANT = auto() 2664 OBJECT = auto() 2665 INET = auto() 2666 NULL = auto() 2667 UNKNOWN = auto() # Sentinel value, useful for type annotation
An enumeration.
Inherited Members
- enum.Enum
- name
- value
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
2772class AddConstraint(Expression): 2773 arg_types = {"this": False, "expression": False, "enforced": False}
Inherited Members
Inherited Members
2781class Binary(Expression): 2782 arg_types = {"this": True, "expression": True} 2783 2784 @property 2785 def left(self): 2786 return self.this 2787 2788 @property 2789 def right(self): 2790 return self.expression
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Kwarg in special functions like func(kwarg => y).
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
2958class Alias(Expression): 2959 arg_types = {"this": True, "alias": False} 2960 2961 @property 2962 def output_name(self): 2963 return self.alias
output_name
Name of the output column if this expression is a selection.
If the Expression has no output name, an empty string is returned.
Example:
>>> from sqlglot import parse_one >>> parse_one("SELECT a").expressions[0].output_name 'a' >>> parse_one("SELECT b AS c").expressions[0].output_name 'c' >>> parse_one("SELECT 1 + 2").expressions[0].output_name ''
2966class Aliases(Expression): 2967 arg_types = {"this": True, "expressions": True} 2968 2969 @property 2970 def aliases(self): 2971 return self.expressions
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
2990class In(Predicate): 2991 arg_types = { 2992 "this": True, 2993 "expressions": False, 2994 "query": False, 2995 "unnest": False, 2996 "field": False, 2997 "is_global": False, 2998 }
Inherited Members
3001class TimeUnit(Expression): 3002 """Automatically converts unit arg into a var.""" 3003 3004 arg_types = {"unit": False} 3005 3006 def __init__(self, **args): 3007 unit = args.get("unit") 3008 if isinstance(unit, Column): 3009 args["unit"] = Var(this=unit.name) 3010 elif isinstance(unit, Week): 3011 unit.set("this", Var(this=unit.this.name)) 3012 super().__init__(**args)
Automatically converts unit arg into a var.
Inherited Members
Inherited Members
Inherited Members
3028class Func(Condition): 3029 """ 3030 The base class for all function expressions. 3031 3032 Attributes: 3033 is_var_len_args (bool): if set to True the last argument defined in arg_types will be 3034 treated as a variable length argument and the argument's value will be stored as a list. 3035 _sql_names (list): determines the SQL name (1st item in the list) and aliases (subsequent items) 3036 for this function expression. These values are used to map this node to a name during parsing 3037 as well as to provide the function's name during SQL string generation. By default the SQL 3038 name is set to the expression's class name transformed to snake case. 3039 """ 3040 3041 is_var_len_args = False 3042 3043 @classmethod 3044 def from_arg_list(cls, args): 3045 if cls.is_var_len_args: 3046 all_arg_keys = list(cls.arg_types) 3047 # If this function supports variable length argument treat the last argument as such. 3048 non_var_len_arg_keys = all_arg_keys[:-1] if cls.is_var_len_args else all_arg_keys 3049 num_non_var = len(non_var_len_arg_keys) 3050 3051 args_dict = {arg_key: arg for arg, arg_key in zip(args, non_var_len_arg_keys)} 3052 args_dict[all_arg_keys[-1]] = args[num_non_var:] 3053 else: 3054 args_dict = {arg_key: arg for arg, arg_key in zip(args, cls.arg_types)} 3055 3056 return cls(**args_dict) 3057 3058 @classmethod 3059 def sql_names(cls): 3060 if cls is Func: 3061 raise NotImplementedError( 3062 "SQL name is only supported by concrete function implementations" 3063 ) 3064 if "_sql_names" not in cls.__dict__: 3065 cls._sql_names = [camel_to_snake_case(cls.__name__)] 3066 return cls._sql_names 3067 3068 @classmethod 3069 def sql_name(cls): 3070 return cls.sql_names()[0] 3071 3072 @classmethod 3073 def default_parser_mappings(cls): 3074 return {name: cls.from_arg_list for name in cls.sql_names()}
The base class for all function expressions.
Attributes:
- is_var_len_args (bool): if set to True the last argument defined in arg_types will be treated as a variable length argument and the argument's value will be stored as a list.
- _sql_names (list): determines the SQL name (1st item in the list) and aliases (subsequent items) for this function expression. These values are used to map this node to a name during parsing as well as to provide the function's name during SQL string generation. By default the SQL name is set to the expression's class name transformed to snake case.
@classmethod
def
from_arg_list(cls, args):
3043 @classmethod 3044 def from_arg_list(cls, args): 3045 if cls.is_var_len_args: 3046 all_arg_keys = list(cls.arg_types) 3047 # If this function supports variable length argument treat the last argument as such. 3048 non_var_len_arg_keys = all_arg_keys[:-1] if cls.is_var_len_args else all_arg_keys 3049 num_non_var = len(non_var_len_arg_keys) 3050 3051 args_dict = {arg_key: arg for arg, arg_key in zip(args, non_var_len_arg_keys)} 3052 args_dict[all_arg_keys[-1]] = args[num_non_var:] 3053 else: 3054 args_dict = {arg_key: arg for arg, arg_key in zip(args, cls.arg_types)} 3055 3056 return cls(**args_dict)
@classmethod
def
sql_names(cls):
3058 @classmethod 3059 def sql_names(cls): 3060 if cls is Func: 3061 raise NotImplementedError( 3062 "SQL name is only supported by concrete function implementations" 3063 ) 3064 if "_sql_names" not in cls.__dict__: 3065 cls._sql_names = [camel_to_snake_case(cls.__name__)] 3066 return cls._sql_names
Inherited Members
Inherited Members
Inherited Members
3085class Anonymous(Func): 3086 arg_types = {"this": True, "expressions": False} 3087 is_var_len_args = True
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
3115class ArrayConcat(Func): 3116 arg_types = {"this": True, "expressions": False} 3117 is_var_len_args = True
Inherited Members
Inherited Members
3124class ArrayFilter(Func): 3125 arg_types = {"this": True, "expression": True} 3126 _sql_names = ["FILTER", "ARRAY_FILTER"]
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
3157class Cast(Func): 3158 arg_types = {"this": True, "to": True} 3159 3160 @property 3161 def name(self) -> str: 3162 return self.this.name 3163 3164 @property 3165 def to(self): 3166 return self.args["to"] 3167 3168 @property 3169 def output_name(self): 3170 return self.name 3171 3172 def is_type(self, dtype: DataType.Type) -> bool: 3173 return self.to.is_type(dtype)
output_name
Name of the output column if this expression is a selection.
If the Expression has no output name, an empty string is returned.
Example:
>>> from sqlglot import parse_one >>> parse_one("SELECT a").expressions[0].output_name 'a' >>> parse_one("SELECT b AS c").expressions[0].output_name 'c' >>> parse_one("SELECT 1 + 2").expressions[0].output_name ''
Inherited Members
Inherited Members
Inherited Members
3184class Ceil(Func): 3185 arg_types = {"this": True, "decimals": False} 3186 _sql_names = ["CEIL", "CEILING"]
Inherited Members
3189class Coalesce(Func): 3190 arg_types = {"this": True, "expressions": False} 3191 is_var_len_args = True
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
3223class DateAdd(Func, TimeUnit): 3224 arg_types = {"this": True, "expression": True, "unit": False}
Inherited Members
3227class DateSub(Func, TimeUnit): 3228 arg_types = {"this": True, "expression": True, "unit": False}
Inherited Members
3231class DateDiff(Func, TimeUnit): 3232 arg_types = {"this": True, "expression": True, "unit": False}
Inherited Members
Inherited Members
3239class DatetimeAdd(Func, TimeUnit): 3240 arg_types = {"this": True, "expression": True, "unit": False}
Inherited Members
3243class DatetimeSub(Func, TimeUnit): 3244 arg_types = {"this": True, "expression": True, "unit": False}
Inherited Members
3247class DatetimeDiff(Func, TimeUnit): 3248 arg_types = {"this": True, "expression": True, "unit": False}
Inherited Members
3251class DatetimeTrunc(Func, TimeUnit): 3252 arg_types = {"this": True, "unit": True, "zone": False}
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
3279class TimestampAdd(Func, TimeUnit): 3280 arg_types = {"this": True, "expression": True, "unit": False}
Inherited Members
3283class TimestampSub(Func, TimeUnit): 3284 arg_types = {"this": True, "expression": True, "unit": False}
Inherited Members
3287class TimestampDiff(Func, TimeUnit): 3288 arg_types = {"this": True, "expression": True, "unit": False}
Inherited Members
3291class TimestampTrunc(Func, TimeUnit): 3292 arg_types = {"this": True, "unit": True, "zone": False}
Inherited Members
3295class TimeAdd(Func, TimeUnit): 3296 arg_types = {"this": True, "expression": True, "unit": False}
Inherited Members
3299class TimeSub(Func, TimeUnit): 3300 arg_types = {"this": True, "expression": True, "unit": False}
Inherited Members
3303class TimeDiff(Func, TimeUnit): 3304 arg_types = {"this": True, "expression": True, "unit": False}
Inherited Members
Inherited Members
3311class DateFromParts(Func): 3312 _sql_names = ["DATEFROMPARTS"] 3313 arg_types = {"year": True, "month": True, "day": True}
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
3356class Greatest(Func): 3357 arg_types = {"this": True, "expressions": False} 3358 is_var_len_args = True
Inherited Members
Inherited Members
Inherited Members
Inherited Members
3373class IfNull(Func): 3374 arg_types = {"this": True, "expression": False} 3375 _sql_names = ["IFNULL", "NVL"]
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
3402class Least(Func): 3403 arg_types = {"this": True, "expressions": False} 3404 is_var_len_args = True
Inherited Members
Inherited Members
3411class Levenshtein(Func): 3412 arg_types = { 3413 "this": True, 3414 "expression": False, 3415 "ins_cost": False, 3416 "del_cost": False, 3417 "sub_cost": False, 3418 }
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
3454class Matches(Func): 3455 """Oracle/Snowflake decode. 3456 https://docs.oracle.com/cd/B19306_01/server.102/b14200/functions040.htm 3457 Pattern matching MATCHES(value, search1, result1, ...searchN, resultN, else) 3458 """ 3459 3460 arg_types = {"this": True, "expressions": True} 3461 is_var_len_args = True
Oracle/Snowflake decode. https://docs.oracle.com/cd/B19306_01/server.102/b14200/functions040.htm Pattern matching MATCHES(value, search1, result1, ...searchN, resultN, else)
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
3510class ApproxQuantile(Quantile): 3511 arg_types = {"this": True, "quantile": True, "accuracy": False, "weight": False}
Inherited Members
3514class ReadCSV(Func): 3515 _sql_names = ["READ_CSV"] 3516 is_var_len_args = True 3517 arg_types = {"this": True, "expressions": False}
Inherited Members
3520class Reduce(Func): 3521 arg_types = {"this": True, "initial": True, "merge": True, "finish": False}
Inherited Members
3524class RegexpExtract(Func): 3525 arg_types = { 3526 "this": True, 3527 "expression": True, 3528 "position": False, 3529 "occurrence": False, 3530 "group": False, 3531 }
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
3580class StrPosition(Func): 3581 arg_types = { 3582 "this": True, 3583 "substr": True, 3584 "position": False, 3585 "instance": False, 3586 }
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
3660class Trim(Func): 3661 arg_types = { 3662 "this": True, 3663 "expression": False, 3664 "position": False, 3665 "collation": False, 3666 }
Inherited Members
3669class TsOrDsAdd(Func, TimeUnit): 3670 arg_types = {"this": True, "expression": True, "unit": False}
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
3695class UnixToTime(Func): 3696 arg_types = {"this": True, "scale": False, "zone": False, "hours": False, "minutes": False} 3697 3698 SECONDS = Literal.string("seconds") 3699 MILLIS = Literal.string("millis") 3700 MICROS = Literal.string("micros")
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
Inherited Members
3723class XMLTable(Func): 3724 arg_types = {"this": True, "passing": False, "columns": False, "by_ref": False}
Inherited Members
Inherited Members
Inherited Members
3735class Merge(Expression): 3736 arg_types = {"this": True, "using": True, "on": True, "expressions": True}
Inherited Members
Inherited Members
def
maybe_parse( sql_or_expression: str | sqlglot.expressions.Expression, *, into: Union[str, Type[sqlglot.expressions.Expression], Collection[Union[str, Type[sqlglot.expressions.Expression]]], NoneType] = None, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, prefix: Optional[str] = None, copy: bool = False, **opts) -> sqlglot.expressions.Expression:
3768def maybe_parse( 3769 sql_or_expression: str | Expression, 3770 *, 3771 into: t.Optional[IntoType] = None, 3772 dialect: DialectType = None, 3773 prefix: t.Optional[str] = None, 3774 copy: bool = False, 3775 **opts, 3776) -> Expression: 3777 """Gracefully handle a possible string or expression. 3778 3779 Example: 3780 >>> maybe_parse("1") 3781 (LITERAL this: 1, is_string: False) 3782 >>> maybe_parse(to_identifier("x")) 3783 (IDENTIFIER this: x, quoted: False) 3784 3785 Args: 3786 sql_or_expression: the SQL code string or an expression 3787 into: the SQLGlot Expression to parse into 3788 dialect: the dialect used to parse the input expressions (in the case that an 3789 input expression is a SQL string). 3790 prefix: a string to prefix the sql with before it gets parsed 3791 (automatically includes a space) 3792 copy: whether or not to copy the expression. 3793 **opts: other options to use to parse the input expressions (again, in the case 3794 that an input expression is a SQL string). 3795 3796 Returns: 3797 Expression: the parsed or given expression. 3798 """ 3799 if isinstance(sql_or_expression, Expression): 3800 if copy: 3801 return sql_or_expression.copy() 3802 return sql_or_expression 3803 3804 import sqlglot 3805 3806 sql = str(sql_or_expression) 3807 if prefix: 3808 sql = f"{prefix} {sql}" 3809 return sqlglot.parse_one(sql, read=dialect, into=into, **opts)
Gracefully handle a possible string or expression.
Example:
>>> maybe_parse("1") (LITERAL this: 1, is_string: False) >>> maybe_parse(to_identifier("x")) (IDENTIFIER this: x, quoted: False)
Arguments:
- sql_or_expression: the SQL code string or an expression
- into: the SQLGlot Expression to parse into
- dialect: the dialect used to parse the input expressions (in the case that an input expression is a SQL string).
- prefix: a string to prefix the sql with before it gets parsed (automatically includes a space)
- copy: whether or not to copy the expression.
- **opts: other options to use to parse the input expressions (again, in the case that an input expression is a SQL string).
Returns:
Expression: the parsed or given expression.
def
union(left, right, distinct=True, dialect=None, **opts):
3955def union(left, right, distinct=True, dialect=None, **opts): 3956 """ 3957 Initializes a syntax tree from one UNION expression. 3958 3959 Example: 3960 >>> union("SELECT * FROM foo", "SELECT * FROM bla").sql() 3961 'SELECT * FROM foo UNION SELECT * FROM bla' 3962 3963 Args: 3964 left (str | Expression): the SQL code string corresponding to the left-hand side. 3965 If an `Expression` instance is passed, it will be used as-is. 3966 right (str | Expression): the SQL code string corresponding to the right-hand side. 3967 If an `Expression` instance is passed, it will be used as-is. 3968 distinct (bool): set the DISTINCT flag if and only if this is true. 3969 dialect (str): the dialect used to parse the input expression. 3970 opts (kwargs): other options to use to parse the input expressions. 3971 Returns: 3972 Union: the syntax tree for the UNION expression. 3973 """ 3974 left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts) 3975 right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts) 3976 3977 return Union(this=left, expression=right, distinct=distinct)
Initializes a syntax tree from one UNION expression.
Example:
>>> union("SELECT * FROM foo", "SELECT * FROM bla").sql() 'SELECT * FROM foo UNION SELECT * FROM bla'
Arguments:
- left (str | Expression): the SQL code string corresponding to the left-hand side.
If an
Expressioninstance is passed, it will be used as-is. - right (str | Expression): the SQL code string corresponding to the right-hand side.
If an
Expressioninstance is passed, it will be used as-is. - distinct (bool): set the DISTINCT flag if and only if this is true.
- dialect (str): the dialect used to parse the input expression.
- opts (kwargs): other options to use to parse the input expressions.
Returns:
Union: the syntax tree for the UNION expression.
def
intersect(left, right, distinct=True, dialect=None, **opts):
3980def intersect(left, right, distinct=True, dialect=None, **opts): 3981 """ 3982 Initializes a syntax tree from one INTERSECT expression. 3983 3984 Example: 3985 >>> intersect("SELECT * FROM foo", "SELECT * FROM bla").sql() 3986 'SELECT * FROM foo INTERSECT SELECT * FROM bla' 3987 3988 Args: 3989 left (str | Expression): the SQL code string corresponding to the left-hand side. 3990 If an `Expression` instance is passed, it will be used as-is. 3991 right (str | Expression): the SQL code string corresponding to the right-hand side. 3992 If an `Expression` instance is passed, it will be used as-is. 3993 distinct (bool): set the DISTINCT flag if and only if this is true. 3994 dialect (str): the dialect used to parse the input expression. 3995 opts (kwargs): other options to use to parse the input expressions. 3996 Returns: 3997 Intersect: the syntax tree for the INTERSECT expression. 3998 """ 3999 left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts) 4000 right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts) 4001 4002 return Intersect(this=left, expression=right, distinct=distinct)
Initializes a syntax tree from one INTERSECT expression.
Example:
>>> intersect("SELECT * FROM foo", "SELECT * FROM bla").sql() 'SELECT * FROM foo INTERSECT SELECT * FROM bla'
Arguments:
- left (str | Expression): the SQL code string corresponding to the left-hand side.
If an
Expressioninstance is passed, it will be used as-is. - right (str | Expression): the SQL code string corresponding to the right-hand side.
If an
Expressioninstance is passed, it will be used as-is. - distinct (bool): set the DISTINCT flag if and only if this is true.
- dialect (str): the dialect used to parse the input expression.
- opts (kwargs): other options to use to parse the input expressions.
Returns:
Intersect: the syntax tree for the INTERSECT expression.
def
except_(left, right, distinct=True, dialect=None, **opts):
4005def except_(left, right, distinct=True, dialect=None, **opts): 4006 """ 4007 Initializes a syntax tree from one EXCEPT expression. 4008 4009 Example: 4010 >>> except_("SELECT * FROM foo", "SELECT * FROM bla").sql() 4011 'SELECT * FROM foo EXCEPT SELECT * FROM bla' 4012 4013 Args: 4014 left (str | Expression): the SQL code string corresponding to the left-hand side. 4015 If an `Expression` instance is passed, it will be used as-is. 4016 right (str | Expression): the SQL code string corresponding to the right-hand side. 4017 If an `Expression` instance is passed, it will be used as-is. 4018 distinct (bool): set the DISTINCT flag if and only if this is true. 4019 dialect (str): the dialect used to parse the input expression. 4020 opts (kwargs): other options to use to parse the input expressions. 4021 Returns: 4022 Except: the syntax tree for the EXCEPT statement. 4023 """ 4024 left = maybe_parse(sql_or_expression=left, dialect=dialect, **opts) 4025 right = maybe_parse(sql_or_expression=right, dialect=dialect, **opts) 4026 4027 return Except(this=left, expression=right, distinct=distinct)
Initializes a syntax tree from one EXCEPT expression.
Example:
>>> except_("SELECT * FROM foo", "SELECT * FROM bla").sql() 'SELECT * FROM foo EXCEPT SELECT * FROM bla'
Arguments:
- left (str | Expression): the SQL code string corresponding to the left-hand side.
If an
Expressioninstance is passed, it will be used as-is. - right (str | Expression): the SQL code string corresponding to the right-hand side.
If an
Expressioninstance is passed, it will be used as-is. - distinct (bool): set the DISTINCT flag if and only if this is true.
- dialect (str): the dialect used to parse the input expression.
- opts (kwargs): other options to use to parse the input expressions.
Returns:
Except: the syntax tree for the EXCEPT statement.
def
select( *expressions: str | sqlglot.expressions.Expression, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, **opts) -> sqlglot.expressions.Select:
4030def select(*expressions: str | Expression, dialect: DialectType = None, **opts) -> Select: 4031 """ 4032 Initializes a syntax tree from one or multiple SELECT expressions. 4033 4034 Example: 4035 >>> select("col1", "col2").from_("tbl").sql() 4036 'SELECT col1, col2 FROM tbl' 4037 4038 Args: 4039 *expressions: the SQL code string to parse as the expressions of a 4040 SELECT statement. If an Expression instance is passed, this is used as-is. 4041 dialect: the dialect used to parse the input expressions (in the case that an 4042 input expression is a SQL string). 4043 **opts: other options to use to parse the input expressions (again, in the case 4044 that an input expression is a SQL string). 4045 4046 Returns: 4047 Select: the syntax tree for the SELECT statement. 4048 """ 4049 return Select().select(*expressions, dialect=dialect, **opts)
Initializes a syntax tree from one or multiple SELECT expressions.
Example:
>>> select("col1", "col2").from_("tbl").sql() 'SELECT col1, col2 FROM tbl'
Arguments:
- *expressions: the SQL code string to parse as the expressions of a SELECT statement. If an Expression instance is passed, this is used as-is.
- dialect: the dialect used to parse the input expressions (in the case that an input expression is a SQL string).
- **opts: other options to use to parse the input expressions (again, in the case that an input expression is a SQL string).
Returns:
Select: the syntax tree for the SELECT statement.
4052def from_(*expressions, dialect=None, **opts) -> Select: 4053 """ 4054 Initializes a syntax tree from a FROM expression. 4055 4056 Example: 4057 >>> from_("tbl").select("col1", "col2").sql() 4058 'SELECT col1, col2 FROM tbl' 4059 4060 Args: 4061 *expressions (str | Expression): the SQL code string to parse as the FROM expressions of a 4062 SELECT statement. If an Expression instance is passed, this is used as-is. 4063 dialect (str): the dialect used to parse the input expression (in the case that the 4064 input expression is a SQL string). 4065 **opts: other options to use to parse the input expressions (again, in the case 4066 that the input expression is a SQL string). 4067 4068 Returns: 4069 Select: the syntax tree for the SELECT statement. 4070 """ 4071 return Select().from_(*expressions, dialect=dialect, **opts)
Initializes a syntax tree from a FROM expression.
Example:
>>> from_("tbl").select("col1", "col2").sql() 'SELECT col1, col2 FROM tbl'
Arguments:
- *expressions (str | Expression): the SQL code string to parse as the FROM expressions of a SELECT statement. If an Expression instance is passed, this is used as-is.
- dialect (str): the dialect used to parse the input expression (in the case that the input expression is a SQL string).
- **opts: other options to use to parse the input expressions (again, in the case that the input expression is a SQL string).
Returns:
Select: the syntax tree for the SELECT statement.
def
update( table, properties, where=None, from_=None, dialect=None, **opts) -> sqlglot.expressions.Update:
4074def update(table, properties, where=None, from_=None, dialect=None, **opts) -> Update: 4075 """ 4076 Creates an update statement. 4077 4078 Example: 4079 >>> update("my_table", {"x": 1, "y": "2", "z": None}, from_="baz", where="id > 1").sql() 4080 "UPDATE my_table SET x = 1, y = '2', z = NULL FROM baz WHERE id > 1" 4081 4082 Args: 4083 *properties (Dict[str, Any]): dictionary of properties to set which are 4084 auto converted to sql objects eg None -> NULL 4085 where (str): sql conditional parsed into a WHERE statement 4086 from_ (str): sql statement parsed into a FROM statement 4087 dialect (str): the dialect used to parse the input expressions. 4088 **opts: other options to use to parse the input expressions. 4089 4090 Returns: 4091 Update: the syntax tree for the UPDATE statement. 4092 """ 4093 update = Update(this=maybe_parse(table, into=Table, dialect=dialect)) 4094 update.set( 4095 "expressions", 4096 [ 4097 EQ(this=maybe_parse(k, dialect=dialect, **opts), expression=convert(v)) 4098 for k, v in properties.items() 4099 ], 4100 ) 4101 if from_: 4102 update.set( 4103 "from", 4104 maybe_parse(from_, into=From, dialect=dialect, prefix="FROM", **opts), 4105 ) 4106 if isinstance(where, Condition): 4107 where = Where(this=where) 4108 if where: 4109 update.set( 4110 "where", 4111 maybe_parse(where, into=Where, dialect=dialect, prefix="WHERE", **opts), 4112 ) 4113 return update
Creates an update statement.
Example:
>>> update("my_table", {"x": 1, "y": "2", "z": None}, from_="baz", where="id > 1").sql() "UPDATE my_table SET x = 1, y = '2', z = NULL FROM baz WHERE id > 1"
Arguments:
- *properties (Dict[str, Any]): dictionary of properties to set which are auto converted to sql objects eg None -> NULL
- where (str): sql conditional parsed into a WHERE statement
- from_ (str): sql statement parsed into a FROM statement
- dialect (str): the dialect used to parse the input expressions.
- **opts: other options to use to parse the input expressions.
Returns:
Update: the syntax tree for the UPDATE statement.
4116def delete(table, where=None, dialect=None, **opts) -> Delete: 4117 """ 4118 Builds a delete statement. 4119 4120 Example: 4121 >>> delete("my_table", where="id > 1").sql() 4122 'DELETE FROM my_table WHERE id > 1' 4123 4124 Args: 4125 where (str|Condition): sql conditional parsed into a WHERE statement 4126 dialect (str): the dialect used to parse the input expressions. 4127 **opts: other options to use to parse the input expressions. 4128 4129 Returns: 4130 Delete: the syntax tree for the DELETE statement. 4131 """ 4132 return Delete( 4133 this=maybe_parse(table, into=Table, dialect=dialect, **opts), 4134 where=Where(this=where) 4135 if isinstance(where, Condition) 4136 else maybe_parse(where, into=Where, dialect=dialect, prefix="WHERE", **opts), 4137 )
Builds a delete statement.
Example:
>>> delete("my_table", where="id > 1").sql() 'DELETE FROM my_table WHERE id > 1'
Arguments:
- where (str|Condition): sql conditional parsed into a WHERE statement
- dialect (str): the dialect used to parse the input expressions.
- **opts: other options to use to parse the input expressions.
Returns:
Delete: the syntax tree for the DELETE statement.
4140def condition(expression, dialect=None, **opts) -> Condition: 4141 """ 4142 Initialize a logical condition expression. 4143 4144 Example: 4145 >>> condition("x=1").sql() 4146 'x = 1' 4147 4148 This is helpful for composing larger logical syntax trees: 4149 >>> where = condition("x=1") 4150 >>> where = where.and_("y=1") 4151 >>> Select().from_("tbl").select("*").where(where).sql() 4152 'SELECT * FROM tbl WHERE x = 1 AND y = 1' 4153 4154 Args: 4155 *expression (str | Expression): the SQL code string to parse. 4156 If an Expression instance is passed, this is used as-is. 4157 dialect (str): the dialect used to parse the input expression (in the case that the 4158 input expression is a SQL string). 4159 **opts: other options to use to parse the input expressions (again, in the case 4160 that the input expression is a SQL string). 4161 4162 Returns: 4163 Condition: the expression 4164 """ 4165 return maybe_parse( # type: ignore 4166 expression, 4167 into=Condition, 4168 dialect=dialect, 4169 **opts, 4170 )
Initialize a logical condition expression.
Example:
>>> condition("x=1").sql() 'x = 1'This is helpful for composing larger logical syntax trees:
>>> where = condition("x=1") >>> where = where.and_("y=1") >>> Select().from_("tbl").select("*").where(where).sql() 'SELECT * FROM tbl WHERE x = 1 AND y = 1'
Arguments:
- *expression (str | Expression): the SQL code string to parse. If an Expression instance is passed, this is used as-is.
- dialect (str): the dialect used to parse the input expression (in the case that the input expression is a SQL string).
- **opts: other options to use to parse the input expressions (again, in the case that the input expression is a SQL string).
Returns:
Condition: the expression
4173def and_(*expressions, dialect=None, **opts) -> And: 4174 """ 4175 Combine multiple conditions with an AND logical operator. 4176 4177 Example: 4178 >>> and_("x=1", and_("y=1", "z=1")).sql() 4179 'x = 1 AND (y = 1 AND z = 1)' 4180 4181 Args: 4182 *expressions (str | Expression): the SQL code strings to parse. 4183 If an Expression instance is passed, this is used as-is. 4184 dialect (str): the dialect used to parse the input expression. 4185 **opts: other options to use to parse the input expressions. 4186 4187 Returns: 4188 And: the new condition 4189 """ 4190 return _combine(expressions, And, dialect, **opts)
Combine multiple conditions with an AND logical operator.
Example:
>>> and_("x=1", and_("y=1", "z=1")).sql() 'x = 1 AND (y = 1 AND z = 1)'
Arguments:
- *expressions (str | Expression): the SQL code strings to parse. If an Expression instance is passed, this is used as-is.
- dialect (str): the dialect used to parse the input expression.
- **opts: other options to use to parse the input expressions.
Returns:
And: the new condition
4193def or_(*expressions, dialect=None, **opts) -> Or: 4194 """ 4195 Combine multiple conditions with an OR logical operator. 4196 4197 Example: 4198 >>> or_("x=1", or_("y=1", "z=1")).sql() 4199 'x = 1 OR (y = 1 OR z = 1)' 4200 4201 Args: 4202 *expressions (str | Expression): the SQL code strings to parse. 4203 If an Expression instance is passed, this is used as-is. 4204 dialect (str): the dialect used to parse the input expression. 4205 **opts: other options to use to parse the input expressions. 4206 4207 Returns: 4208 Or: the new condition 4209 """ 4210 return _combine(expressions, Or, dialect, **opts)
Combine multiple conditions with an OR logical operator.
Example:
>>> or_("x=1", or_("y=1", "z=1")).sql() 'x = 1 OR (y = 1 OR z = 1)'
Arguments:
- *expressions (str | Expression): the SQL code strings to parse. If an Expression instance is passed, this is used as-is.
- dialect (str): the dialect used to parse the input expression.
- **opts: other options to use to parse the input expressions.
Returns:
Or: the new condition
4213def not_(expression, dialect=None, **opts) -> Not: 4214 """ 4215 Wrap a condition with a NOT operator. 4216 4217 Example: 4218 >>> not_("this_suit='black'").sql() 4219 "NOT this_suit = 'black'" 4220 4221 Args: 4222 expression (str | Expression): the SQL code strings to parse. 4223 If an Expression instance is passed, this is used as-is. 4224 dialect (str): the dialect used to parse the input expression. 4225 **opts: other options to use to parse the input expressions. 4226 4227 Returns: 4228 Not: the new condition 4229 """ 4230 this = condition( 4231 expression, 4232 dialect=dialect, 4233 **opts, 4234 ) 4235 return Not(this=_wrap_operator(this))
Wrap a condition with a NOT operator.
Example:
>>> not_("this_suit='black'").sql() "NOT this_suit = 'black'"
Arguments:
- expression (str | Expression): the SQL code strings to parse. If an Expression instance is passed, this is used as-is.
- dialect (str): the dialect used to parse the input expression.
- **opts: other options to use to parse the input expressions.
Returns:
Not: the new condition
def
to_identifier(name, quoted=None):
4255def to_identifier(name, quoted=None): 4256 """Builds an identifier. 4257 4258 Args: 4259 name: The name to turn into an identifier. 4260 quoted: Whether or not force quote the identifier. 4261 4262 Returns: 4263 The identifier ast node. 4264 """ 4265 4266 if name is None: 4267 return None 4268 4269 if isinstance(name, Identifier): 4270 identifier = name 4271 elif isinstance(name, str): 4272 identifier = Identifier( 4273 this=name, 4274 quoted=not re.match(SAFE_IDENTIFIER_RE, name) if quoted is None else quoted, 4275 ) 4276 else: 4277 raise ValueError(f"Name needs to be a string or an Identifier, got: {name.__class__}") 4278 return identifier
Builds an identifier.
Arguments:
- name: The name to turn into an identifier.
- quoted: Whether or not force quote the identifier.
Returns:
The identifier ast node.
4284def to_interval(interval: str | Literal) -> Interval: 4285 """Builds an interval expression from a string like '1 day' or '5 months'.""" 4286 if isinstance(interval, Literal): 4287 if not interval.is_string: 4288 raise ValueError("Invalid interval string.") 4289 4290 interval = interval.this 4291 4292 interval_parts = INTERVAL_STRING_RE.match(interval) # type: ignore 4293 4294 if not interval_parts: 4295 raise ValueError("Invalid interval string.") 4296 4297 return Interval( 4298 this=Literal.string(interval_parts.group(1)), 4299 unit=Var(this=interval_parts.group(2)), 4300 )
Builds an interval expression from a string like '1 day' or '5 months'.
def
to_table( sql_path: Union[str, sqlglot.expressions.Table, NoneType], **kwargs) -> Optional[sqlglot.expressions.Table]:
4313def to_table(sql_path: t.Optional[str | Table], **kwargs) -> t.Optional[Table]: 4314 """ 4315 Create a table expression from a `[catalog].[schema].[table]` sql path. Catalog and schema are optional. 4316 If a table is passed in then that table is returned. 4317 4318 Args: 4319 sql_path: a `[catalog].[schema].[table]` string. 4320 4321 Returns: 4322 A table expression. 4323 """ 4324 if sql_path is None or isinstance(sql_path, Table): 4325 return sql_path 4326 if not isinstance(sql_path, str): 4327 raise ValueError(f"Invalid type provided for a table: {type(sql_path)}") 4328 4329 catalog, db, table_name = (to_identifier(x) for x in split_num_words(sql_path, ".", 3)) 4330 return Table(this=table_name, db=db, catalog=catalog, **kwargs)
Create a table expression from a [catalog].[schema].[table] sql path. Catalog and schema are optional.
If a table is passed in then that table is returned.
Arguments:
- sql_path: a
[catalog].[schema].[table]string.
Returns:
A table expression.
4333def to_column(sql_path: str | Column, **kwargs) -> Column: 4334 """ 4335 Create a column from a `[table].[column]` sql path. Schema is optional. 4336 4337 If a column is passed in then that column is returned. 4338 4339 Args: 4340 sql_path: `[table].[column]` string 4341 Returns: 4342 Table: A column expression 4343 """ 4344 if sql_path is None or isinstance(sql_path, Column): 4345 return sql_path 4346 if not isinstance(sql_path, str): 4347 raise ValueError(f"Invalid type provided for column: {type(sql_path)}") 4348 table_name, column_name = (to_identifier(x) for x in split_num_words(sql_path, ".", 2)) 4349 return Column(this=column_name, table=table_name, **kwargs)
Create a column from a [table].[column] sql path. Schema is optional.
If a column is passed in then that column is returned.
Arguments:
- sql_path:
[table].[column]string
Returns:
Table: A column expression
def
alias_( expression: str | sqlglot.expressions.Expression, alias: str | sqlglot.expressions.Identifier, table: Union[bool, Sequence[str | sqlglot.expressions.Identifier]] = False, quoted: Optional[bool] = None, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, **opts):
4352def alias_( 4353 expression: str | Expression, 4354 alias: str | Identifier, 4355 table: bool | t.Sequence[str | Identifier] = False, 4356 quoted: t.Optional[bool] = None, 4357 dialect: DialectType = None, 4358 **opts, 4359): 4360 """Create an Alias expression. 4361 4362 Example: 4363 >>> alias_('foo', 'bar').sql() 4364 'foo AS bar' 4365 4366 >>> alias_('(select 1, 2)', 'bar', table=['a', 'b']).sql() 4367 '(SELECT 1, 2) AS bar(a, b)' 4368 4369 Args: 4370 expression: the SQL code strings to parse. 4371 If an Expression instance is passed, this is used as-is. 4372 alias: the alias name to use. If the name has 4373 special characters it is quoted. 4374 table: Whether or not to create a table alias, can also be a list of columns. 4375 quoted: whether or not to quote the alias 4376 dialect: the dialect used to parse the input expression. 4377 **opts: other options to use to parse the input expressions. 4378 4379 Returns: 4380 Alias: the aliased expression 4381 """ 4382 exp = maybe_parse(expression, dialect=dialect, **opts) 4383 alias = to_identifier(alias, quoted=quoted) 4384 4385 if table: 4386 table_alias = TableAlias(this=alias) 4387 exp.set("alias", table_alias) 4388 4389 if not isinstance(table, bool): 4390 for column in table: 4391 table_alias.append("columns", to_identifier(column, quoted=quoted)) 4392 4393 return exp 4394 4395 # We don't set the "alias" arg for Window expressions, because that would add an IDENTIFIER node in 4396 # the AST, representing a "named_window" [1] construct (eg. bigquery). What we want is an ALIAS node 4397 # for the complete Window expression. 4398 # 4399 # [1]: https://cloud.google.com/bigquery/docs/reference/standard-sql/window-function-calls 4400 4401 if "alias" in exp.arg_types and not isinstance(exp, Window): 4402 exp = exp.copy() 4403 exp.set("alias", alias) 4404 return exp 4405 return Alias(this=exp, alias=alias)
Create an Alias expression.
Example:
>>> alias_('foo', 'bar').sql() 'foo AS bar'>>> alias_('(select 1, 2)', 'bar', table=['a', 'b']).sql() '(SELECT 1, 2) AS bar(a, b)'
Arguments:
- expression: the SQL code strings to parse. If an Expression instance is passed, this is used as-is.
- alias: the alias name to use. If the name has special characters it is quoted.
- table: Whether or not to create a table alias, can also be a list of columns.
- quoted: whether or not to quote the alias
- dialect: the dialect used to parse the input expression.
- **opts: other options to use to parse the input expressions.
Returns:
Alias: the aliased expression
def
subquery(expression, alias=None, dialect=None, **opts):
4408def subquery(expression, alias=None, dialect=None, **opts): 4409 """ 4410 Build a subquery expression. 4411 4412 Example: 4413 >>> subquery('select x from tbl', 'bar').select('x').sql() 4414 'SELECT x FROM (SELECT x FROM tbl) AS bar' 4415 4416 Args: 4417 expression (str | Expression): the SQL code strings to parse. 4418 If an Expression instance is passed, this is used as-is. 4419 alias (str | Expression): the alias name to use. 4420 dialect (str): the dialect used to parse the input expression. 4421 **opts: other options to use to parse the input expressions. 4422 4423 Returns: 4424 Select: a new select with the subquery expression included 4425 """ 4426 4427 expression = maybe_parse(expression, dialect=dialect, **opts).subquery(alias) 4428 return Select().from_(expression, dialect=dialect, **opts)
Build a subquery expression.
Example:
>>> subquery('select x from tbl', 'bar').select('x').sql() 'SELECT x FROM (SELECT x FROM tbl) AS bar'
Arguments:
- expression (str | Expression): the SQL code strings to parse. If an Expression instance is passed, this is used as-is.
- alias (str | Expression): the alias name to use.
- dialect (str): the dialect used to parse the input expression.
- **opts: other options to use to parse the input expressions.
Returns:
Select: a new select with the subquery expression included
def
column( col: str | sqlglot.expressions.Identifier, table: Union[str, sqlglot.expressions.Identifier, NoneType] = None, schema: Union[str, sqlglot.expressions.Identifier, NoneType] = None, quoted: Optional[bool] = None) -> sqlglot.expressions.Column:
4431def column( 4432 col: str | Identifier, 4433 table: t.Optional[str | Identifier] = None, 4434 schema: t.Optional[str | Identifier] = None, 4435 quoted: t.Optional[bool] = None, 4436) -> Column: 4437 """ 4438 Build a Column. 4439 4440 Args: 4441 col: column name 4442 table: table name 4443 schema: schema name 4444 quoted: whether or not to force quote each part 4445 Returns: 4446 Column: column instance 4447 """ 4448 return Column( 4449 this=to_identifier(col, quoted=quoted), 4450 table=to_identifier(table, quoted=quoted), 4451 schema=to_identifier(schema, quoted=quoted), 4452 )
Build a Column.
Arguments:
- col: column name
- table: table name
- schema: schema name
- quoted: whether or not to force quote each part
Returns:
Column: column instance
def
cast( expression: str | sqlglot.expressions.Expression, to: str | sqlglot.expressions.DataType | sqlglot.expressions.DataType.Type, **opts) -> sqlglot.expressions.Cast:
4455def cast(expression: str | Expression, to: str | DataType | DataType.Type, **opts) -> Cast: 4456 """Cast an expression to a data type. 4457 4458 Example: 4459 >>> cast('x + 1', 'int').sql() 4460 'CAST(x + 1 AS INT)' 4461 4462 Args: 4463 expression: The expression to cast. 4464 to: The datatype to cast to. 4465 4466 Returns: 4467 A cast node. 4468 """ 4469 expression = maybe_parse(expression, **opts) 4470 return Cast(this=expression, to=DataType.build(to, **opts))
Cast an expression to a data type.
Example:
>>> cast('x + 1', 'int').sql() 'CAST(x + 1 AS INT)'
Arguments:
- expression: The expression to cast.
- to: The datatype to cast to.
Returns:
A cast node.
4473def table_(table, db=None, catalog=None, quoted=None, alias=None) -> Table: 4474 """Build a Table. 4475 4476 Args: 4477 table (str | Expression): column name 4478 db (str | Expression): db name 4479 catalog (str | Expression): catalog name 4480 4481 Returns: 4482 Table: table instance 4483 """ 4484 return Table( 4485 this=to_identifier(table, quoted=quoted), 4486 db=to_identifier(db, quoted=quoted), 4487 catalog=to_identifier(catalog, quoted=quoted), 4488 alias=TableAlias(this=to_identifier(alias)) if alias else None, 4489 )
Build a Table.
Arguments:
- table (str | Expression): column name
- db (str | Expression): db name
- catalog (str | Expression): catalog name
Returns:
Table: table instance
def
values( values: Iterable[Tuple[Any, ...]], alias: Optional[str] = None, columns: Union[Iterable[str], Dict[str, sqlglot.expressions.DataType], NoneType] = None) -> sqlglot.expressions.Values:
4492def values( 4493 values: t.Iterable[t.Tuple[t.Any, ...]], 4494 alias: t.Optional[str] = None, 4495 columns: t.Optional[t.Iterable[str] | t.Dict[str, DataType]] = None, 4496) -> Values: 4497 """Build VALUES statement. 4498 4499 Example: 4500 >>> values([(1, '2')]).sql() 4501 "VALUES (1, '2')" 4502 4503 Args: 4504 values: values statements that will be converted to SQL 4505 alias: optional alias 4506 columns: Optional list of ordered column names or ordered dictionary of column names to types. 4507 If either are provided then an alias is also required. 4508 If a dictionary is provided then the first column of the values will be casted to the expected type 4509 in order to help with type inference. 4510 4511 Returns: 4512 Values: the Values expression object 4513 """ 4514 if columns and not alias: 4515 raise ValueError("Alias is required when providing columns") 4516 table_alias = ( 4517 TableAlias(this=to_identifier(alias), columns=[to_identifier(x) for x in columns]) 4518 if columns 4519 else TableAlias(this=to_identifier(alias) if alias else None) 4520 ) 4521 expressions = [convert(tup) for tup in values] 4522 if columns and isinstance(columns, dict): 4523 types = list(columns.values()) 4524 expressions[0].set( 4525 "expressions", 4526 [cast(x, types[i]) for i, x in enumerate(expressions[0].expressions)], 4527 ) 4528 return Values( 4529 expressions=expressions, 4530 alias=table_alias, 4531 )
Build VALUES statement.
Example:
>>> values([(1, '2')]).sql() "VALUES (1, '2')"
Arguments:
- values: values statements that will be converted to SQL
- alias: optional alias
- columns: Optional list of ordered column names or ordered dictionary of column names to types. If either are provided then an alias is also required. If a dictionary is provided then the first column of the values will be casted to the expected type in order to help with type inference.
Returns:
Values: the Values expression object
4534def var(name: t.Optional[str | Expression]) -> Var: 4535 """Build a SQL variable. 4536 4537 Example: 4538 >>> repr(var('x')) 4539 '(VAR this: x)' 4540 4541 >>> repr(var(column('x', table='y'))) 4542 '(VAR this: x)' 4543 4544 Args: 4545 name: The name of the var or an expression who's name will become the var. 4546 4547 Returns: 4548 The new variable node. 4549 """ 4550 if not name: 4551 raise ValueError(f"Cannot convert empty name into var.") 4552 4553 if isinstance(name, Expression): 4554 name = name.name 4555 return Var(this=name)
Build a SQL variable.
Example:
>>> repr(var('x')) '(VAR this: x)'>>> repr(var(column('x', table='y'))) '(VAR this: x)'
Arguments:
- name: The name of the var or an expression who's name will become the var.
Returns:
The new variable node.
def
rename_table( old_name: str | sqlglot.expressions.Table, new_name: str | sqlglot.expressions.Table) -> sqlglot.expressions.AlterTable:
4558def rename_table(old_name: str | Table, new_name: str | Table) -> AlterTable: 4559 """Build ALTER TABLE... RENAME... expression 4560 4561 Args: 4562 old_name: The old name of the table 4563 new_name: The new name of the table 4564 4565 Returns: 4566 Alter table expression 4567 """ 4568 old_table = to_table(old_name) 4569 new_table = to_table(new_name) 4570 return AlterTable( 4571 this=old_table, 4572 actions=[ 4573 RenameTable(this=new_table), 4574 ], 4575 )
Build ALTER TABLE... RENAME... expression
Arguments:
- old_name: The old name of the table
- new_name: The new name of the table
Returns:
Alter table expression
4578def convert(value) -> Expression: 4579 """Convert a python value into an expression object. 4580 4581 Raises an error if a conversion is not possible. 4582 4583 Args: 4584 value (Any): a python object 4585 4586 Returns: 4587 Expression: the equivalent expression object 4588 """ 4589 if isinstance(value, Expression): 4590 return value 4591 if value is None: 4592 return NULL 4593 if isinstance(value, bool): 4594 return Boolean(this=value) 4595 if isinstance(value, str): 4596 return Literal.string(value) 4597 if isinstance(value, float) and math.isnan(value): 4598 return NULL 4599 if isinstance(value, numbers.Number): 4600 return Literal.number(value) 4601 if isinstance(value, tuple): 4602 return Tuple(expressions=[convert(v) for v in value]) 4603 if isinstance(value, list): 4604 return Array(expressions=[convert(v) for v in value]) 4605 if isinstance(value, dict): 4606 return Map( 4607 keys=[convert(k) for k in value], 4608 values=[convert(v) for v in value.values()], 4609 ) 4610 if isinstance(value, datetime.datetime): 4611 datetime_literal = Literal.string( 4612 (value if value.tzinfo else value.replace(tzinfo=datetime.timezone.utc)).isoformat() 4613 ) 4614 return TimeStrToTime(this=datetime_literal) 4615 if isinstance(value, datetime.date): 4616 date_literal = Literal.string(value.strftime("%Y-%m-%d")) 4617 return DateStrToDate(this=date_literal) 4618 raise ValueError(f"Cannot convert {value}")
Convert a python value into an expression object.
Raises an error if a conversion is not possible.
Arguments:
- value (Any): a python object
Returns:
Expression: the equivalent expression object
def
replace_children(expression, fun):
4621def replace_children(expression, fun): 4622 """ 4623 Replace children of an expression with the result of a lambda fun(child) -> exp. 4624 """ 4625 for k, v in expression.args.items(): 4626 is_list_arg = isinstance(v, list) 4627 4628 child_nodes = v if is_list_arg else [v] 4629 new_child_nodes = [] 4630 4631 for cn in child_nodes: 4632 if isinstance(cn, Expression): 4633 for child_node in ensure_collection(fun(cn)): 4634 new_child_nodes.append(child_node) 4635 child_node.parent = expression 4636 child_node.arg_key = k 4637 else: 4638 new_child_nodes.append(cn) 4639 4640 expression.args[k] = new_child_nodes if is_list_arg else seq_get(new_child_nodes, 0)
Replace children of an expression with the result of a lambda fun(child) -> exp.
def
column_table_names(expression):
4643def column_table_names(expression): 4644 """ 4645 Return all table names referenced through columns in an expression. 4646 4647 Example: 4648 >>> import sqlglot 4649 >>> column_table_names(sqlglot.parse_one("a.b AND c.d AND c.e")) 4650 ['c', 'a'] 4651 4652 Args: 4653 expression (sqlglot.Expression): expression to find table names 4654 4655 Returns: 4656 list: A list of unique names 4657 """ 4658 return list(dict.fromkeys(column.table for column in expression.find_all(Column)))
Return all table names referenced through columns in an expression.
Example:
>>> import sqlglot >>> column_table_names(sqlglot.parse_one("a.b AND c.d AND c.e")) ['c', 'a']
Arguments:
- expression (sqlglot.Expression): expression to find table names
Returns:
list: A list of unique names
def
table_name(table) -> str:
4661def table_name(table) -> str: 4662 """Get the full name of a table as a string. 4663 4664 Args: 4665 table (exp.Table | str): table expression node or string. 4666 4667 Examples: 4668 >>> from sqlglot import exp, parse_one 4669 >>> table_name(parse_one("select * from a.b.c").find(exp.Table)) 4670 'a.b.c' 4671 4672 Returns: 4673 The table name. 4674 """ 4675 4676 table = maybe_parse(table, into=Table) 4677 4678 if not table: 4679 raise ValueError(f"Cannot parse {table}") 4680 4681 return ".".join( 4682 part 4683 for part in ( 4684 table.text("catalog"), 4685 table.text("db"), 4686 table.name, 4687 ) 4688 if part 4689 )
Get the full name of a table as a string.
Arguments:
- table (exp.Table | str): table expression node or string.
Examples:
>>> from sqlglot import exp, parse_one >>> table_name(parse_one("select * from a.b.c").find(exp.Table)) 'a.b.c'
Returns:
The table name.
def
replace_tables(expression, mapping):
4692def replace_tables(expression, mapping): 4693 """Replace all tables in expression according to the mapping. 4694 4695 Args: 4696 expression (sqlglot.Expression): expression node to be transformed and replaced. 4697 mapping (Dict[str, str]): mapping of table names. 4698 4699 Examples: 4700 >>> from sqlglot import exp, parse_one 4701 >>> replace_tables(parse_one("select * from a.b"), {"a.b": "c"}).sql() 4702 'SELECT * FROM c' 4703 4704 Returns: 4705 The mapped expression. 4706 """ 4707 4708 def _replace_tables(node): 4709 if isinstance(node, Table): 4710 new_name = mapping.get(table_name(node)) 4711 if new_name: 4712 return to_table( 4713 new_name, 4714 **{k: v for k, v in node.args.items() if k not in ("this", "db", "catalog")}, 4715 ) 4716 return node 4717 4718 return expression.transform(_replace_tables)
Replace all tables in expression according to the mapping.
Arguments:
- expression (sqlglot.Expression): expression node to be transformed and replaced.
- mapping (Dict[str, str]): mapping of table names.
Examples:
>>> from sqlglot import exp, parse_one >>> replace_tables(parse_one("select * from a.b"), {"a.b": "c"}).sql() 'SELECT * FROM c'
Returns:
The mapped expression.
def
replace_placeholders(expression, *args, **kwargs):
4721def replace_placeholders(expression, *args, **kwargs): 4722 """Replace placeholders in an expression. 4723 4724 Args: 4725 expression (sqlglot.Expression): expression node to be transformed and replaced. 4726 args: positional names that will substitute unnamed placeholders in the given order. 4727 kwargs: keyword arguments that will substitute named placeholders. 4728 4729 Examples: 4730 >>> from sqlglot import exp, parse_one 4731 >>> replace_placeholders( 4732 ... parse_one("select * from :tbl where ? = ?"), "a", "b", tbl="foo" 4733 ... ).sql() 4734 'SELECT * FROM foo WHERE a = b' 4735 4736 Returns: 4737 The mapped expression. 4738 """ 4739 4740 def _replace_placeholders(node, args, **kwargs): 4741 if isinstance(node, Placeholder): 4742 if node.name: 4743 new_name = kwargs.get(node.name) 4744 if new_name: 4745 return to_identifier(new_name) 4746 else: 4747 try: 4748 return to_identifier(next(args)) 4749 except StopIteration: 4750 pass 4751 return node 4752 4753 return expression.transform(_replace_placeholders, iter(args), **kwargs)
Replace placeholders in an expression.
Arguments:
- expression (sqlglot.Expression): expression node to be transformed and replaced.
- args: positional names that will substitute unnamed placeholders in the given order.
- kwargs: keyword arguments that will substitute named placeholders.
Examples:
>>> from sqlglot import exp, parse_one >>> replace_placeholders( ... parse_one("select * from :tbl where ? = ?"), "a", "b", tbl="foo" ... ).sql() 'SELECT * FROM foo WHERE a = b'
Returns:
The mapped expression.
def
expand( expression: sqlglot.expressions.Expression, sources: Dict[str, sqlglot.expressions.Subqueryable], copy=True) -> sqlglot.expressions.Expression:
4756def expand(expression: Expression, sources: t.Dict[str, Subqueryable], copy=True) -> Expression: 4757 """Transforms an expression by expanding all referenced sources into subqueries. 4758 4759 Examples: 4760 >>> from sqlglot import parse_one 4761 >>> expand(parse_one("select * from x AS z"), {"x": parse_one("select * from y")}).sql() 4762 'SELECT * FROM (SELECT * FROM y) AS z /* source: x */' 4763 4764 Args: 4765 expression: The expression to expand. 4766 sources: A dictionary of name to Subqueryables. 4767 copy: Whether or not to copy the expression during transformation. Defaults to True. 4768 4769 Returns: 4770 The transformed expression. 4771 """ 4772 4773 def _expand(node: Expression): 4774 if isinstance(node, Table): 4775 name = table_name(node) 4776 source = sources.get(name) 4777 if source: 4778 subquery = source.subquery(node.alias or name) 4779 subquery.comments = [f"source: {name}"] 4780 return subquery 4781 return node 4782 4783 return expression.transform(_expand, copy=copy)
Transforms an expression by expanding all referenced sources into subqueries.
Examples:
>>> from sqlglot import parse_one >>> expand(parse_one("select * from x AS z"), {"x": parse_one("select * from y")}).sql() 'SELECT * FROM (SELECT * FROM y) AS z /* source: x */'
Arguments:
- expression: The expression to expand.
- sources: A dictionary of name to Subqueryables.
- copy: Whether or not to copy the expression during transformation. Defaults to True.
Returns:
The transformed expression.
def
func( name: str, *args, dialect: Union[str, sqlglot.dialects.dialect.Dialect, Type[sqlglot.dialects.dialect.Dialect], NoneType] = None, **kwargs) -> sqlglot.expressions.Func:
4786def func(name: str, *args, dialect: DialectType = None, **kwargs) -> Func: 4787 """ 4788 Returns a Func expression. 4789 4790 Examples: 4791 >>> func("abs", 5).sql() 4792 'ABS(5)' 4793 4794 >>> func("cast", this=5, to=DataType.build("DOUBLE")).sql() 4795 'CAST(5 AS DOUBLE)' 4796 4797 Args: 4798 name: the name of the function to build. 4799 args: the args used to instantiate the function of interest. 4800 dialect: the source dialect. 4801 kwargs: the kwargs used to instantiate the function of interest. 4802 4803 Note: 4804 The arguments `args` and `kwargs` are mutually exclusive. 4805 4806 Returns: 4807 An instance of the function of interest, or an anonymous function, if `name` doesn't 4808 correspond to an existing `sqlglot.expressions.Func` class. 4809 """ 4810 if args and kwargs: 4811 raise ValueError("Can't use both args and kwargs to instantiate a function.") 4812 4813 from sqlglot.dialects.dialect import Dialect 4814 4815 args = tuple(convert(arg) for arg in args) 4816 kwargs = {key: convert(value) for key, value in kwargs.items()} 4817 4818 parser = Dialect.get_or_raise(dialect)().parser() 4819 from_args_list = parser.FUNCTIONS.get(name.upper()) 4820 4821 if from_args_list: 4822 function = from_args_list(args) if args else from_args_list.__self__(**kwargs) # type: ignore 4823 else: 4824 kwargs = kwargs or {"expressions": args} 4825 function = Anonymous(this=name, **kwargs) 4826 4827 for error_message in function.error_messages(args): 4828 raise ValueError(error_message) 4829 4830 return function
Returns a Func expression.
Examples:
>>> func("abs", 5).sql() 'ABS(5)'>>> func("cast", this=5, to=DataType.build("DOUBLE")).sql() 'CAST(5 AS DOUBLE)'
Arguments:
- name: the name of the function to build.
- args: the args used to instantiate the function of interest.
- dialect: the source dialect.
- kwargs: the kwargs used to instantiate the function of interest.
Note:
The arguments
argsandkwargsare mutually exclusive.
Returns:
An instance of the function of interest, or an anonymous function, if
namedoesn't correspond to an existingsqlglot.expressions.Funcclass.
def
true():
4833def true(): 4834 """ 4835 Returns a true Boolean expression. 4836 """ 4837 return Boolean(this=True)
Returns a true Boolean expression.
def
false():
4840def false(): 4841 """ 4842 Returns a false Boolean expression. 4843 """ 4844 return Boolean(this=False)
Returns a false Boolean expression.
def
null():
Returns a Null expression.